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Preface 


This text describes the features of a dialect of LISP known as INTERLISP. IN- 
TERLISP stands for “Interactive Lisp.”’ It provides a rich program development 
and problem prototyping environment. 

There is strong agreement among LISP developers and users about what the 
basic functions of LISP are. All of these are described in the first few chapters of 
this book. But there is no “standard” for LISP and it is unlikely that we will see 
one in the near future. To date, the best standard that exists is the INTERLISP 
Reference Manual. This manual is edited and maintained by staff members of 
the Xerox Corporation’s Palo Alto Research Center, Palo Alto, CA and Special 
Information Systems Division, Pasadena, CA. 

For all of the detail and wealth of information contained in the INTERLISP 
Reference Manual [irm78, irm83], it remains a remarkably obtuse document. 
Some say that it is user-hostile. One must have extreme familiarity with IN- 
TERLISP, usually through the tutelage of an INTERLISP guru, to be able to 
use it efficiently. This text attempts to correct this problem by describing most of 
the major functions, capabilities, and packages provided by INTERLISP. It is 
augmented by numerous examples taken from actual experience as well as many 
technical papers published in the open AI literature. Where appropriate, refer- 
ences to the INTERLISP Reference Manual [irm78, irm83] will be made using 
the notation (IRM x.y.z) where x,y,z refer to the chapter, section, and para- 
graph of the IRM respectively. 

This text is based upon experience gained using INTERLISP on an IBM 
3081 under VM/SP (version 3.0), INTERLISP-D on a Xerox 1100 Scientific In- 
formation Processor (through the Fugue release), and INTERLISP-10 on a 
DECSystem-20 under TOPS-20 (release dated 26-SEP-83). 

It is not my intent to teach you how to “‘program’”’ in LISP in this text. There 
are numerous books that explain the essential features of LISP programming 
from the viewpoint of the novice. Many of these are mentioned in the references, 
but a notable volume is that of Winston and Horn: 


vii 


viii Preface 
Winston, P. and Horn, B.K.P. 
Lisp 
Addison-Wesley, Reading, MA, 1981 


whose first few chapters provide a basic introduction to LISP programming. If 
you have not programmed in LISP before, you may also want to consult 


Touretzsky, D. 
LISP: A Gentle Introduction to Symbolic Computation 


Harper & Row, New York, 1983 


Wilensky, R. 
LISPCraft 
W. Norton & Sons, San Francisco, 1984 


The text is divided at a logical breakpoint. Chapters 1 through 16 discuss 
features that are largely found in most LISP systems, although they may often go 
by different names or have different implementations. Chapters 17 through 31 
discuss features that provide INTERLISP with its power as an interactive pro- 
gramming environment. A second volume is contemplated that will discuss the 
INTERLISP-D implementation. Tentatively, this volume will be entitled 


Interlisp: The Interactive Programming Environment 


You will find this current text replete with examples of LISP functions that 
have been described and (sometimes) commented. This reflects a bias of mine 
that you understand a language by reading programs or functions written in the 
language. That is, we all learn programming by analogy; we look at how some- 
body else has written a program and copy the essential elements. Sometimes we 
copy their style and faults as well. The functional code presented in this text has, 
si the most part, been tested on one of the INTERLISP systems mentioned 
above. 


STEPHEN H. KAISLER 


Silver Spring, Maryland 
March, 1986 








Acknowledgments 


No book is ever completed without the assistance of a great many people. Let me 
take this opportunity to thank a few of those who assisted me. Jerry Alexander of 
Analytics, Inc. encouraged the completion of the book as did numerous Interlisp 
programmers and adherents who believed that something better than the IRM 
was needed. Charles Kellogg of MCC and John Vittal and Beau Shiel of Xerox 
reviewed the manuscript and provided many cogent comments. Jim Gaughan, 
my former editor; Carol Beasley, who stepped in in his absence; and Maria Tay- 
lor, my current editor, were all instrumental in seeing the project through to 
completion. Also, I would like to especially thank Sandra Renner, their secre- 
tary, who handled numerous queries and phone calls. Finally, I want to ac- 
knowledge the contribution of the family cats, Sprite and Gizmo, who carefully 
monitored the progress of the book by sitting in front of the computer terminal 
while I typed away. 


S.H.K. 


Viii Preface 


Winston, P. and Horn, B.K.P. 
Lisp 
Addison-Wesley, Reading, MA, 1981 


whose first few chapters provide a basic introduction to LISP programming. If 
you have not programmed in LISP before, you may also want to consult 


Touretzsky, D. 
LISP: A Gentle Introduction to Symbolic Computation 


Harper & Row, New York, 1983 


Wilensky, R. 
LISPCraft 
W. Norton & Sons, San Francisco, 1984 


The text is divided at a logical breakpoint. Chapters 1 through 16 discuss 
features that are largely found in most LISP systems, although they may often go 
by different names or have different implementations. Chapters 17 through 31 
discuss features that provide INTERLISP with its power as an interactive pro- 
gramming environment. A second volume is contemplated that will discuss the 
INTERLISP-D implementation. Tentatively, this volume will be entitled 


Interlisp: The Interactive Programming Environment 


You will find this current text replete with examples of LISP functions that 
have been described and (sometimes) commented. This reflects a bias of mine 
that you understand a language by reading programs or functions written in the 
language. That is, we all learn programming by analogy; we look at how some- 
body else has written a program and copy the essential elements. Sometimes we 
copy their style and faults as well. The functional code presented in this text has, 
for the most part, been tested on one of the INTERLISP systems mentioned 
above. 


STEPHEN H. KAISLER 


Silver Spring, Maryland 
March, 1986 





7 a eS eg | 


— = 


-_----—— ee 


Acknowledgments 


No book is ever completed without the assistance of a great many people. Let me 
take this opportunity to thank a few of those who assisted me. Jerry Alexander of 
Analytics, Inc. encouraged the completion of the book as did numerous Interlisp 
programmers and adherents who believed that something better than the IRM 
was needed. Charles Kellogg of MCC and John Vittal and Beau Shiel of Xerox 
reviewed the manuscript and provided many cogent comments. Jim Gaughan, 
my former editor; Carol Beasley, who stepped in in his absence; and Maria Tay- 
lor, my current editor, were all instrumental in seeing the project through to 
completion. Also, I would like to especially thank Sandra Renner, their secre- 
tary, who handled numerous queries and phone calls. Finally, I want to ac- 
knowledge the contribution of the family cats, Sprite and Gizmo, who carefully 
monitored the progress of the book by sitting in front of the computer terminal 
while I typed away. 


S.H.K. 





SS a ae ——_— ——-- 


= 


Contents 


1. INTRODUCTION 1 


1.1 Why Lisp? 2 
1.1.1 Symbolic Computation 2 


1.1.2 Information Representation by Lists 3 
1.1.3 Primitive Functions 3 

1.1.4 Function Composition 4 

1.1.5 Functions versus Data 4 

1.1.6 The EVAL Function 3 


1.2 Lisp Dialects S 
1.2.1 MACLISP/ZetaLisp S 
1.2.2 FranzLisp 7 
1.2.3. Portable Standard Lisp fa 
1.2.4 CommonLisp i 

1.3. Lisp as a Programming Environment 8 
1.3.1 Multiple Data Types 9 
1.3.2 Modular Programming 9 
1.3.3 Deferred Binding 10 
1.3.4 Interactive Development 10 
1.3.5 Flexible Control Structures 11 
1.3.6 Pattern Matching Facilities 11 
1.3.7 Language Extensibility 12 


1.4 Lisp as a Conceptual Environment 12 
1.5 Structure of the Text 14 
1.6 Comments on the Text 16 
2. LISP DATA STRUCTURES 19 


2.1 Literal Atoms 19 
2.1.1 Pnames 21 
2.1.2 Value Cells 21 
2.1.3 Property Lists 21 


xi 


xii Contents 


pr | 


2.3 


y 
2.6 
ya | 


2.1.4 Function Definition Cells 21 

2.1.5 Creating Atoms 22 

2.1.6 Binding Variable Values 23 

2.1.7 Variable Typing and Declaration 24 
Numbers 25 

2.2.1 Integers 25 

2.2.2 Floating Point Numbers 26 

2.2.3 Complex Numbers 27 

2.2.4 Conversion between Numeric Classes 27 
Lists 27 

Arrays 29 

2.4.1 Dimensionality 30 

2.4.2 Specification and Creation of Arrays 31 
2.4.3 Hash Arrays 31 

Strings 32 

Records and User-Defined Datatypes 32 

Files 33 


3. PRIMITIVE FUNCTIONS 35 


x 


3.2 


3.3 


3.4 
3.5 


3.6 


A 


Taking Lists Apart: CAR and CDR 35 

3.1.1 CAR/CDR Combinations 37 

Putting Lists Together: CONS, LIST, and APPEND 40 
3.2.1 CONS: Constructing Lists 40 

3.2.2 LIST: Making Lists 42 

3.2.3. APPEND: Concatenating Lists 45 

3.2.4 Creating (NIL) 48 

Physical Structure Replacement: RPLACA and RPLACD 48 
3.3.1 Replacing the CAR Cell 49 

3.3.2 Replacing the CDR Cell 50 

3.3.3 Replacing the CAR and CDR of a Cell 52 
Preventing Evaluation 53 

Conditional Execution: COND 56 

3.5.1 Executing a COND Expression 57 

3.5.2 The Default Clause 38 

3.5.3 Test Phrase Values 58 

Multiple Case Selection: SELECTQ 60 

3.6.1 Executing a SELECTQ Expression 60 
3.6.2 SELECTQ Examples 62 

3.6.3 A Definition for SELECTQ 63 

3.6.4 SELECTC: Selecting on Constants 64 
Iterative Evaluation: PROG 6S 

3.7.1 Binding of PROG Variables 66 

3.7.2 Variations on PROG 68 

3.7.3 Transfer of Control 69 

3.7.4 Exiting PROGs 71 


Contents xiii 


3.7.5 Implementing a DO-WHILE-UNTIL Construct 71 
3.7.6 Other LISP Forms 7S 


3.8 Value Assignment: SET and SETQ 76 
3.9 Setting an Atom’s Value Cell 77 

3.9.1 Binding Atoms from a File 77 

3.9.2 Getting and Setting the Top Level Value 78 
FUNDAMENTAL PREDICATES 81 
4.1 Atom Testing: ATOM and LITATOM 81 


4.2 


4.3 


4.5 


4.6 


4.1.1 An Alternative Atomic Predicate 83 
Numeric Predicates 84 

4.2.1 Testing for Numbers 84 

4.2.2 Testing for Zero 85 

4.2.3 A Generalized Zero Predicate 86 

4.2.4 Testing the Type of Number 87 

String Testing: STRINGP 88 

Array Testing: ARRAYP 89 

List Testing: LISTP and TAILP 90 

4.5.1 Testing for the Tail of a List 91 

4.5.2 Counting the CDRs to Produce a Tail 93 
Testing for Equality 94 

4.6.1 EQ versus EQUAL 94 

4.6.2 Atomic Equality 97 

4.6.3. Numeric Equality 99 

4.6.4 Testing Equality of Length 100 

4.6.5 Testing Complex or Circular Structures 101 
4.6.6 Testing for Non-Equality 102 

4.6.7 Testing for Null 103 


4.7 Testing Variable Bindings 103 

4.8 Determining Membership in a List 10S 

LOGICAL CONNECTIVES AND PREDICATES 109 
5.1 Logical Conjunction 109 


Ded 


ded 


5.4 


S55 


5.1.1. An Application of AND 111 

Logical Disjunction 111 

5.2.1. An Application of the OR Function 113 
Logical Negation 113 

5.3.1 Computing the Logical Negation 113 
5.3.2 Creating Negated S-expressions 114 
Universal Quantification 116 

5.4.1 A Definition for EVERY 117 

5.4.2 Applications of EVERY 118 
Existential Quantification 119 

5.5.1 A Definition for SOME 120 


xiv Contents 


6. LIST MANIPULATION 123 


6.1 
6.2 


6.3 


6.4 


6.5 


6.6 


6.7 


6.8 


6.9 


Creating Lists: LIST 123 

Concatenating Lists 125 

6.2.1 NCONC: Normal Concatenation “125 
6.2.2 TCONC: One at a Time Concatenation 128 
6.2.3 LCONC: Concatenating Lists 130 

6.2.4 ATTACH: Concatenating at the Front 132 
6.2.5 Variations on Concatenation 133 

Sublist Extraction 136 

6.3.1 Extracting the Last Element 136 

6.3.2 Extracting the Tailing N Elements 137 
6.3.3 Extracting the Last N Elements 139 
6.3.4 Extracting from the Nth Element 142 
Copying and Reversing Lists 143 

6.4.1 Copying List Elements 144 

6.4.2 Copying All List Elements 146 

6.4.3 Copying with Reversal 148 

6.4.4 Removing Elements from a List 149 
Modifying Lists by Substitution 151 . 
6.5.1 A General Substitution Function: SUBST 151 
6.5.2 Substituting by Segments: LSUBST 153 
6.5.3 Substituting by Association: SUBLIS 154 
6.5.4 Substituting by Pairing: SUBPAIR 157 
Logical Operations on Lists 161 

6.6.1 Logical Difference 162 

6.6.2 Logical Intersection 166 

6.6.3 Logical Union 167 

Sorting Lists 168 

6.7.1 A Basic Sorting Function 169 

6.7.2 Numeric Sorting 170 

6.7.3 Alphameric Sorting 171 

6.7.4 Comparing Two Lists 173 

Length Functions 177 

6.8.1 Finding the Length of a List 177 

6.8.2 Counting List Cells 178 

6.8.3 Counting Down a List 179 

Merging Lists 180 

6.9.1 Merging Two Lists 181 

6.9.2 Merging with Insertion 183 


6.10 Association Functions 184 


6.10.1 Searching Lists for Associations 184 
6.10.2 Replacing an Association List Value 186 
6.10.3 Removing an Entry 187 

6.10.4 Adding a Value to an Entry 189 





6.11 


Contents xv 


Searching Lists 189 
6.11.1 Searching Lists in Property List Format 190 
6.11.2 Replacing Elements in Place in a List 191 


PROPERTY LIST FUNCTIONS 193 


7.1 


5 oe 


task 


7.4 


ff 


7.6 


Concept of the Property List 193 

7.1.1 The Uniqueness of Atoms 194 

Getting a Property 195 

7.2.1 Getting the Entire Property List 197 
Putting Properties 198 

7.3.1 Assigning Multiple Properties 201 

7.3.2 Setting the Property List 201 

7.3.3 Defining a Property for Multiple Atoms 202 
Modifying Property Lists 203 

7.4.1 Adding a Property 203 

7.4.2 Removing a Property 206 

7.4.3 Removing the Property List 207 

7.4.4 Changing Property Names 208 

Obtaining the Property Names of an Atom 210 
7.5.1 Obtaining the System Property Names 211 
Extracting A Property Sublist 211 


FUNCTION DEFINITION AND EVALUATION 213 


8.1 


8.2 


8.3 
8.4 


8.5 


8.6 
8.7 


Function Types 213 

8.1.1 To Evaluate or Not 214 

8.1.2 To Spread or Not 215 

8.1.3 Compiled Functions 216 

8.1.4 Summary of Function Types 216 
8.1.5 Determining the Function Type 217 
Defining Functions 218 

8.2.1 Syntax of a Function Definition 218 
8.2.2 Defining a Function: DEFINEQ 219 
8.2.3 Defining a Function: DEFINE 220 
8.2.4 The Effect of DFNFLG 221 

8.2.5 Alternative Defining Forms 222 
Retrieving a Function Definition 223 
Setting a Function Definition 224 

8.4.1 Alternative Forms of PUTD 225 
Copying Function Definitions 225 

8.5.1 A MOVD Example 226 

Function Predicates 228 

Argument List Functions 229 

8.7.1 Determining the Argument Type 229 
8.7.2 Determining the Number of Arguments 231 


xvi 


10. 


Contents 


8.7.3 Obtaining the Argument List 234 | 
8.7.4 Accessing the Arguments of a Nospread Function 235 | 
8.7.5 Setting the Arguments of a Nospread Function 236 
8.8 Function Evaluation 237 | 
8.8.1 Updating a Database Variable 237 : 
8.8.2 A-list Evaluation 238 
8.8.3 Constant Evaluation 238 
8.9 Function Application 239 
8.9.1 APPLYing to an Indefinite Number of Arguments 241 
8.10 Repetitive Execution 241 
8.11 Generators 243 
8.11.1 Initializing a Generator 244 
8.12 Macros 245 
8.12.1 Definition of Macros 246 
8.12.2 Expansion of Macros 249 
8.12.3. A Function for Defining Macros 250 


ATOM MANIPULATION 253 


9.1 Rules for Atom Names 254 
9.2 Creating Atoms 255 
9.2.1 GENSYM: Generating a Symbol 256 
9.2.2 MKATOM: Creating Atoms from Strings 259 
9.2.3 Making an Atom from a Substring 260 
9.3 Packing and Unpacking Atoms 262 
9.3.1 Packing Atoms 262 
9.3.2 Unpacking Atoms 263 
9.3.3 Using PACK and UNPACK 264 
9.4 Character Conversion 265 
9.4.1 CHCON: Converting to a Number 265 
9.4.2 CHARACTER: Converting to the PNAME 
Equivalent 266 
9.4.3 Character Code Structures 267 
9.4.4 Character Translation 268 
9.5 Determining PNAME Length 270 
9.6 Extracting Characters 271 
9.7 Selecting Alternatives by Character Codes 273 
9.8 Case Functions 273 


STRING MANIPULATION FUNCTIONS 275 


10.1 Creating a String 275 
10.1.1 Allocating a String Pointer 277 
10.2 Extracting Substrings 277 
10.2.1 The SUBSTRING Function 278 
10.2.2 Getting the Next or Last Character 279 


11. 


10.3 


10.4 


10.5 


10.6 


10.7 


10.8 


Contents xvii 


Concatenating Strings 280 

10.3.1 Concatenating a List of Objects 281 
Testing Strings 282 

10.4.1 Determining String Existence 282 
10.4.2 Testing the Equality of Strings 282 
10.4.3. Testing String Membership 283 
Replacing Elements of a String 284 

10.5.1 Replacing Elements with Character Codes 285 
Searching a String 286 

10.6.1 Searching a String for a Character 290 
10.6.2 Creating Bit Tables 291 

String Operations 292 

10.7.1 Inserting into a String 292 

10.7.2 Deleting from a String 293 

10.7.3 Substituting into a String 294 
Trimming a String 294 


ARRAY MANIPULATION FUNCTIONS 297 


11.1 


11.2 


Creating an Array: INTERLISP-10 297 

11.1.1 Creating an Array: INTERLISP-D 299 

Manipulating Arrays 299 

11.2.1 Obtaining the Array Size 300 

11.2.2 Obtaining the Array Type 300 

11.2.3 Validating an Array Pointer 301 

11.2.4 Obtaining a Pointer to the Beginning of an 
Array 301 

11.2.5 Setting the Value of an Array Element 302 

11.2.6 Retrieving the Value of an Array Element 304 

11.2.7 Copying Arrays 305 

11.2.8 Comparing Two Arrays 306 

Hash Arrays 307 

11.3.1 Creating and Testing Hash Arrays 308 

11.3.2 Storing into and Retrieving from a Hash Array 309 

11.3.3 Applying a Function to a Hash Array 312 

11.3.4 Dumping Hash Arrays 312 

11.3.5 Overflow Handling 313 

A Matrix Package 315 

11.4.1 Defining a Matrix 315 

11.4.2 Getting a Matrix Element 317 

11.4.3 Setting a Matrix Element 319 

11.4.4 Basic Matrix Operations 319 

Sorting Using Arrays 325 

11.5.1 BubbleSort 325 

11.5.2 Selection Sorting 327 


xviii 


12. 


13. 


Contents 


MAPPING FUNCTIONS 329 


12.1 


Generic Mapping 329 
12.1.1 Returning a List of Values 331 
12.1.2 Mapping on Successive Elements 332 
12.1.3 Mapping on Successive Elements: MAPCONC 334 
12.1.4 Mapping over Two Arguments 336 
12.1.5 Mapping Across Atoms: MAPATOMS 338 
12.1.6 A Generic Printing Function 339 
Applying Functions to Subsets 341 
Specifying an Argument as a Function: FUNCTION 342 
The FUNARG Mechanism 344 
12.4.1 Using FUNARGs 344 
12.4.2 Constructing FUNARGs to be Passed as 
Functions 346 
APPLYing a Function to its Arguments 348 
12.5.1 Determining S-expression Depth 349 


ARITHMETIC FUNCTIONS 351 


13.1 


13.2 


13.3 


Integer Functions 352 

13.1.1 Integer Addition 352 

13.1.2 Integer Subtraction 353 

13.1.3 Integer Multiplication 355 

13.1.4 Integer Division 356 

13.1.5 Minimum and Maximum 357 

13.1.6 Integer Modulus 358 

13.1.7 Converting to an Integer 358 

Integer Predicates 359 

13.2.1 Boolean Predicates 359 

13.2.2 Predicates for Testing Equality 360 

13.2.3 Predicates for Testing Characteristics 362 
Manipulating Integers 365 

13.3.1 Logical Manipulations 366 

13.3.2 Integer Shift Functions 367 

13.3.3 Integer Conversion 369 

13.3.4 The Greatest Common Divisor 369 

Floating Point Functions 370 

13.4.1 Floating Point Addition 370 

13.4.2 Floating Point Subtraction 371 

13.4.3 Floating Point Multiplication 372 

13.4.4 Floating Point Division 372 

13.4.5 Testing Equality of Floating Point Numbers 373 
13.4.6 Floating Point Boolean Functions 374 

13.4.7 Floating Point Minimum and Maximum 374 
13.4.8 Converting a Number to Floating Point Format 375 


EEE == 


14. 


13.5 


13.6 


13.7 


Contents xix 


Mixed Arithmetic Functions 375 

13.5.1 Computing the Absolute Value 376 
Special Arithmetic Functions att 

13.6.1 Trigonometric Functions 377 

13.6.2 Inverse Trigonometric Functions 378 
13.6.3 Exponentiation 379 

13.6.4 Square Root 380 

13.6.5 Logarithms 381 

13.6.6 Random Number Generation 382 
More Arithmetic Functions 383 

13.7.1 Statistical Functions 384 

13.7.2 Complex Arithmetic 386 

13.7.3. Additional Arithmetic Functions 391 


INPUT FUNCTIONS 395 


14.1 


14.2 


14.4 


14.5 


READ: The General Case 395 

14.1.1. Effect of Control Characters 397 
READing: Special Cases 401 

14.2.1 RATOM: Reading an Atom 401 

14.2.2 Reading up to an Atom 402 

14.2.3 Testing Atom Demarcators 403 

14.2.4 RSTRING: Reading a String 40S 

14.2.5 READC: Reading a Character 40S 

14.2.6 Reading the Last Character 406 

14.2.7 Looking Ahead in the Input Stream 407 
14.2.8 READLINE: Reading a Terminal Line 408 
14.2.9 Reading from a File 409 

14.2.10 Skipping S-expressions in a File 410 
Input Predicates 412 

14.3.1 READP: Testing Input 412 

14.3.2 Waiting for Input 414 

Concept of the Read Table 415 

14.4.1 Syntax Classes 415 

14.4.2 Getting the Syntax Class 417 

14.4.3 Setting the Syntax Class 418 

14.4.4 Testing the Syntax Class 420 

14.4.5 Read Macros: Defining User Syntax Classes 421 
14.4.6 Standard Read Macro Characters 424 
14.4.7 Read Macro Functions 425 

14.4.8 BQUOTE: An Example of a SPLICE Macro 426 
Read Table Functions 428 

14.5.1 Testing a Read Table 428 

14.5.2 Obtaining a Read Table Address 428 
14.5.3 Setting a Read Table 429 

14.5.4 Copying a Read Table 429 


xX Contents 


15. 


14.6 


14.7 


Line Buffering 430 

14.6.1 Enabling and Disabling Line Buffering 431 
14.6.2 Clearing the Line Buffer 434 

14.6.3 Accessing the Buffer’s Contents 434 
14.6.4 Resetting the Line and System Buffers 435 
The Askuser Package 436 

14.7.1 ASKUSER 436 

14.7.2. Key Completion 438 

14.7.3 Key List Format 438 

14.7.4 The Default Key List 439 

14.7.5 Key List Options 439 

14.7.6 Key List Construction 443 

14.7.7 Special Keys 444 


OUTPUT FUNCTIONS 447 


15.1 


15.2 


15.3 
15.4 


15.5 


Printing S-expressions: PRINx 448 

15.1.1 PRINI 448 ; 

15.1.2 Printing with Separators 449 

15.1.3 Printing with a Carriage Return 451 
15.1.4 Printing-Bells 452 

15.1.5 User-Defined Printing 452 

15.1.6 Printing Unusual Data Structures 454 
15.1.7 Writing Expressions to a File 457 
Print Control Functions 458 

15.2.1 Printing Multiple Spaces 458 

15.2.2 Printing a Carriage Return 460 

15.2.3 Tabbing 460 

Setting the Print Level 462 

Printing Numbers 465 : 

15.4.1 Format Conversion 465 

15.4.2 Fixed Point Format 466 

15.4.3 Floating Point Format 467 

15.4.4 Changing the Integer Radix 468 
15.4.5 Changing the Floating Point Output Format 469 . 
Terminal Tables 469 

15.5.1 Terminal Syntax Classes 471 

15.5.2 Establishing a Terminal Table 472 
15.5.3 Getting a Terminal Table Address 472 
15.5.4 Testing a Terminal Table 473 

15.5.5 Copying Terminal Tables 473 

15.5.6 Resetting the Terminal Table 474 
Terminal Control 474 

15.6.1 Echo Modes 474 

15.6.2 Echo Control 476 

15.6.3 Character and Line Deletion Control 477 





i 
it 


16. 


13.2 


15.8 


Contents Xxi 


15.6.4. Converting to Upper Case on Typein 480 
15.6.5 Line Length Control 480 

Prettyprinting 483 

15.7.1 Generalized Prettyprinting 483 

15.7.2 Prettyprinting to the Terminal 487 
15.7.3 Displaying Prettyprinted Definitions 488 
15.7.4 Prettyprinting Symbolic Files 489 

15.7.5 Prettyprinting Control Variables 489 
The Printout Package 493 

15.8.1 Horizontal Spacing Commands 494 
15.8.2 Vertical Spacing Commands 495 

15.8.3 Printing Specifications 49S 

15.8.4 Structure Specifications 496 


FILE MANAGEMENT AND OPERATIONS 499 


16.1 


16.2 


16.3 


16.4 


16.5 


16.6 


16.7 


16.8 


File Structures and Names 499 

16.1.1 The VM/SP File System 499 

16.1.2 The INTERLISP-D and INTERLISP-10 File 
Systems 500 

File Declarations S01 

16.2.1 The Primary File ‘T’ 501 

16.2.2 Declaring the Primary Input File S01 

16.2.3 Declaring the Primary Output File 503 

16.2.4 Testing Input/Output Files S05 

16.2.5 File Name Recognition SOS 

Opening a File 506 

16.3.1 A General File Open Function 507 

16.3.2 A Predicate for Testing Open Files 509 

Getting and Setting File Attributes 510 

16.4.1 Setting File Attributes 513 

Closing Files 513 

16.5.1 Basic Closing Functions 513 

16.5.2 Closing All Files 514 

16.5.3. The Whenclose Package S15 

Other File Operations Sy 

16.6.1 Deleting Files $17 

16.6.2 Renaming Files 518 

Manipulating File Names 518 

16.7.1 Unpacking a File Name 519 

16.7.2 Constructing File Names 519 

16.7.3 Accessing a File Name Field 520 

Random Access Files , 521 

16.8.1 Manipulating the File Pointer a22 

16.8.2 Testing for Random Accessibility 523 

16.8.3 Searching a File 524 


17. 


Contents 


16.9 


16.8.4 Copying Bytes from File to File 526 
16.8.5 Testing for an End of File $27 

Saving and Restoring a User’s Virtual Memory: 
SYSIN/SYSOUT 527 

16.9.1 Saving Your Virtual Memory 528 
16.9.2 Restoring Your Virtual Memory 529 
16.9.3 Advising SYSOUT Before Saving 530 
16.9.4 Advising SYSOUT After Restoring 531 


16.10 Commenting Function Definitions 532 


16.10.1 Printing Comments 533 
16.10.2 Comment Pointers 534 


THE FILE PACKAGE 537 


17.1 


17.2 


17.3 


Features of the File Package 537 
17.1.1 Marking Changes to Files 538 
17.1.2 Noticing Files 538 

17.1.3 Updating Files 539 

17.1.4 File Package Properties 539 
17.1.5 File Maps 540 

17.1.6 File Package Variables 541 
File Package Commands 342 

17.2.1 Functions 543 

17.2.2 Variables 544 

17.2.3 Adding Variables to a File 348 
17.2.4 Association Lists 550 

17.2.5 Properties SS1 

17.2.6 S-expressions 553 

17.2.7 Evaluation of S-expressions 554 
17.2.8 Commands 554 

17.2.9 Comments 555 

17.2.10 Advice 556 

17.2.11 Macros 557 

17.2.12 File Package Commands 559 
17.2.13 Records 559 

17.2.14 Arrays 560 

17.2.15 CLISP Expressions 561 
17.2.16 Templates 561 

17.2.17 Blocks 561 

17.2.18 Declarations 562 

17.2.19 Files 562 

17.2.20 Variations on Command Structure 563 
File Package Functions 564 

17.3.1 Making Files 565 

17.3.2 Remaking Files 572 

17.3.3 Making Multiple Files $73 
17.3.4 Listing Files $75 


17.4 


17.5 


17.6 


17.9 


Contents xxiii 


17.3.5 Compiling Files 576 

17.3.6 Cleaning Up Files $77 

17.3.7 Determining File Status 578 

17.3.8 WHEREIS: Finding Types in Files S81 
17.3.9 Marking Changes in Files $82 

17.3.10 Determining What has been Changed 584 
17.3.11 Adding to Files 584 

Defining New File Package Types 586 

17.4.1 FILEPKGTYPE 586 

17.4.2 File Package Type Definitions 588 
Manipulating File Package Types 589 

17.5.1 Getting a Type Definition S91 

17.5.2 Creating a Definition 593 

17.5.3 Copying a Definition 594 

17.5.4 Deleting a Definition 596 

17.5.5 Showing Definitions 596 

17.5.6 Editing a Definition 597 

17.5.7 Saving and Unsaving Definitions 598 
17.5.8 Loading a Definition 599 

17.5.9 Renaming an Object 600 

17.5.10 Changing Calling Function Names 601 
17.5.11 Comparing Definitions 603 

17.5.12 Determining Type Existence 604 

17.5.13 Determining the Types of an Object 605 
Defining New File Package Commands 606 

17.6.1 FILEPKGCOM 606 

Manipulating File Package Command Lists 609 
17.7.1 Adding to a File’s COMS 609 

17.7.2 Deleting from a File’s COMS 610 

17.7.3 Determining if an Object is in a Command 611 
17.7.4 Making a New File Package Command 613 
17.7.5 Creating a COMS Variable Name 613 
17.7.6 Smashing a File’s COMS 614 

17.7.7 Moving an Item between Files 615 
Prettyprinting to a File 615 

17.8.1 Prettyprinting Function Definitions 615 
17.8.2 Printing a Definition 619 

17.8.3 Making a File Creation Slug 620 

17.8.4 Determining the File Date 621 

17.8.5 Printing the File Date 622 

17.8.6 Printing Function Definitions on a File 623 
17.8.7 Printing a COMS Message upon Loading 624 
17.8.8 Obtaining the File Changes 624 

Symbolic File Input 625 

17.9.1 Generalized Load 625 

17.9.2 Loading Selected Functions 627 


XXiv 


18. 


19. 


Contents 


17.9.3 Loading Selected Expressions 628 
17.9.4 Editing Functions without Loading 629 
17.9.5 Loading Symbolic Definitions 629 


ERROR HANDLING 631 


18.1 
18.2 


18.3 


18.4 
18.5 
18.6 


How Errors Occur 631 

Catching and Handling Errors 632 

18.2.1 Catching Errors: ERRORTYPELST 632 
18.2.2. An Example of ERRORTYPELIST Usage 634 
Catching Errors in a Computation 635 

18.3.1 Alternative Forms of ERRORSET 637 
18.3.2 Checking for an End of File 638 
Terminal-Initiated Breaks 638 

Types of Errors 640 

Error Handling Functions 648 

18.6.1 Printing Error Messages 648 

18.6.2 Returning from Errors 653 

18.6.3 Obtaining Information about Errors 654 
18.6.4 Entering the Error Routines 655 


THE INTERLISP EDITOR 661 


19.1 


19.2 
19.3 


19.4 


19.5 


Invoking the Editor 661 

19.1.1 Function Editing 661 

19.1.2 Value Editing 666 

19.1.3 Property List Editing 668 

19.1.4 Expression Editing 670 

EDITL: The INTERLISP Editor 671 

Editor Functions 672 

19.3.1 Finding a Pattern 672 

19.3.2 Substituting in an Expression 673 

19.3.3 Changing Names 674 

19.3.4 Searching Files 674 

19.3.5 Tracing Editor Macros 675 

Editor Concepts 675 

19.4.1 The Concept of Currency 675 

19.4.2 The Print Level 676 

19.4.3 Multiple Commands per Line 676 

19.4.4 Pattern Specifications for Searching 676 

Basic Editor Commands 677 

19.5.1 Printing the Current Expression 677 

19.5.2 Descending a Level 678 

19.5.3 Ascending the Edit Chain 678 

19.5.4 Modifying the List Structure 679 

19.5.5 Adding Elements to the End of the Current 
Expression 680 





19.6 


19.5.6 
19.3.7 
19.5.8 


Contents XXV 


Finding an Element 681 
Replacing an Element 682 
Exiting the Editor 682 


An Editor Command Encyclopedia 682 


19.6.1 

19.6.2 

19.6.3 

19.6.4 

19.6.5 

19.6.6 

19.6.7 

19.6.8 

19.6.9 

19.6.10 
19.6.11 
19.6.12 
19.6.13 
19.6.14 
19.6.15 
19.6.16 
19.6.17 
19.6.18 
19.6.19 
19.6.20 
19.6.21 
19.6.22 
19.6.23 
19.6.24 
19.6.25 
19.6.26 
19.6.27 
19.6.28 
19.6.29 
19.6.30 
19.6.31 
19.6.32 
19.6.33 
19.6.34 
19.6.35 
19.6.36 
19.6.37 
19.6.38 
19.6.39 
19.6.40 
19.6.41 
19.6.42 


Inserting After the Current Expression 685 
Inserting Before the Current Expression 686 
Locating a Pattern 686 
Searching Backwards 687 
Inserting Balanced Parentheses 688 
Binding Macro Variables 689 
Backing Up in the Current Expression 690 
Deleting Balanced Parentheses 691 
Capitalization 691 « 

CLISPIFYing Expressions 692 

Command Execution 693 

Deleting Expressions 693 

DWIMIFYing Expressions 694 

Evaluating Input 695 

Embedding 696 


Evaluating an Expression 697 
Examining an Expression 698 
Finding an S-expression 699 


Getting a Definition 701 

Getting a Value 702 

Getting a Comment 703 

Going to a PROG Label 703 
Conditional Listing 703 

Inserting into an Expression 704 
Joining Conditional Expressions 70S 
Locating an S-expression 706 

Inserting and Removing Left Parentheses 707 
Lower-Case Conversion 708 

Iterative Execution 709 

Macro Definition 709 

Assigning Values to Arguments 711 
Making a Function 712 

Marking and Restoring the Edit Chain 713 
Moving Expressions 714 

Adding to the End of an Expression 715 
Negating the Current Expression 716 
Advancing to the Next Expression 716 
The NIL Command tLe 

Finding the Nth Element 717 

Exiting the Editor 718 

Using the Original Definition 718 
Executing Any One Command 719 


Xxvi Contents 


19.6.43 Printing the Current Expression 719 
19.6.44 Replacing in an Expression 720 

19.6.45 Raising the Case in an Expression 721 
19.6.46 Editing Atoms or Strings 721 

19.6.47 Right Parenthesis In 722 

19.6.48 Right Parenthesis Out 722 

19.6.49 Setting a Literal Atom’s Value 723 

19.6.50 Showing Instances 723 

19.6.51 Splitting Conditional Expressions 724 
19.6.52 Switching Elements in an Expression 725 
19.6.53 Setting a Tentative Edit Marker 726 
19.6.54 THRU and TO: Location Specification 727 
19.6.55 Recursive Editing 727 

19.6.56 Undoing an Editor Command 727 

19.6.57 Moving up the Edit Chain 728 

19.6.58 Extracting from the Current Expression 728 
19.6.59 Inserting Comments 729 

19.6.60 Attention-Changing Commands 730 


20. DEBUGGING FACILITIES 731 


20.1 
20.2 


20.4 


20.5 


TRACE: Tracing a Function 731 

Break Commands 735 

20.2.1 Releasing Breaks 735 

20.2.2 Evaluation in a Break 736 

20.2.3 Returning a Value from a Break 737 
20.2.4 Aborting a Break 737 

20.2.5  Unbreaking a Function 738 

20.2.6 Displaying Arguments and Bindings 738 
20.2.7 Obtaining a Backtrace 741 

20.2.8 Displaying the Entire Stack 744 

20.2.9 Setting the Stack Frame 745 

20.2.10 Setting Values on the Stack 746 
20.2.11 Breakmacros 746 

20.2.12 Breakresetforms 748 

Setting Breakpoints 748 

20.3.1 Function Breakpoints 749 

20.3.2 Defining a Breakpoint 750 

20.3.3 Activating a Breakpoint 754 

20.3.4 Breaking into a Function 756 

20.3.5 BREAKCHECK: When to Break 760 
Unbreaking Functions 761 

20.4.1 Unbreaking a Function: 1 761 

20.4.2 Unbreaking a Function: 2 762 

20.4.3 Unbreaking a Broken-into Function 763 
Break Package Utilities 763 

20.5.1 Reading Break Package Commands 763 


21. 


22. 


23. 


Contents 


20.5.2 Changing Names in Functions 764 
20.5.3 Restoring a Virgin Definition 765 
20.5.4 Printing a Backtrace of the Stack 765 


ADVISING 


21.1 ADVISE: Modifying a Function’s Interface 769 
21.2 UNADVISE: Removing Advice 775 

21.3. READVISEing a Function 776 

21.4 Saving Advice in a File 776 


DWIM: AUTOMATIC ERROR CORRECTION 


22.1 DWIM Modes 779 
22.1.1 A DWIM Example 780 
22.2. DWIM Protocols 781 
22.2.1 Spelling Correction 781 
22.2.2 Parenthesis Errors 782 
22.2.3 Clause Errors 782 
22.3. Error Correction Algorithms 784 
22.3.1 Unbound Atoms 785 
22.3.2 Undefined Functions 787 
22.3.3 Undefined Functions in APPLY 789 
22.4 Enabling DWIM 790 
22.5 DWIMIFYing an Expression 790 
22.5.1 DWIMIFYing a List of Functions 792 
22.5.2 DWIMIFY Variables 793 
22.6 The Spelling Corrector 795 
22.6.1 Choosing a Candidate 795 
22.6.2 Scoring a Candidate 802 
22.7 DWIM Parameters 809 
22.7.1 User-Directed Corrections and Transformations 
22.7.2 The Spelling Lists 812 
22.8 Spelling Functions 814 
22.8.1 Adding a Word to a Spelling List 814 
22.8.2 Finding a Misspelling 822 
22.8.3 Fixing the Spelling of a Word 823 
22.8.4 Checking a Function Name Spelling 826 
22.8.5 Correcting File Name Spelling 827 
22.8.6 A Spelling Correction Example 829 


CONVERSATIONAL LISP 


23.1 How CLISP Operates 834 

23.1.1 Translating CLISP Statements 834 
23.2 Operators 835 

23.2.1 List Operators 835 

23.2.2 Infix Operators 837 


XXVii 


769 


779 


810 


833 


XxViii 


24. 


Contents 


23.3 
23.4 


23:9 


23.6 


pa P| 
23.8 


23.9 


23.2.3 Prefix Operators 839 

23.2.4 Operator Precedence 840 

23.2.5 CLISP Declarations 840 

23.2.6 Operator Definitions 842 
Conditional Statements 844 

Iterative Statements 846 

23.4.1 1I.S.Opr Translations 846 

23.4.2 1.S.Type Operators 847 

23.4.3 1.S.Binding Operators 851 
23.4.4 1.S.Selection Operators 852 
23.4.5 1.S.Termination Operators 855 
23.4.6 1.S.Modification Operators 856 
23.4.7 Potential Errors in Iterative Statements 857 
23.4.8 Defining New Iterative Statement Operators 859 
English Phrases 860 

23.5.1 Basic English Forms 861 

23.5.2 Defining New Words 861 
CLISPIFYing 862 

23.6.1 CLISPIFY Variables 863 
CLISP Conventions 865 

CLISP Functions 869 

23.8.1 CLISPIFYing Functions 869 
23.8.2 Disabling CLISP Operators 870 
23.8.3 Storing CLISP Translations 870 
CLISP Variables 871 


23.10 The CHANGETRAN Package 872 


23.10.1 CHANGETRAN Words 872 
23.10.2 Defining New CLISP Words 874 


LISP USER’S PACKAGES 877 


24.1 


24.2 


24.3 
24.4 
24.5 


File System Extensions 877 

24.1.1 Indexing a File 877 

24.1.2 Indexing Multiple Files 878 

24.1.3 Implementing the ALL File Package Type 882 
24.1.4 Editing a File’s History 883 

24.1.5 Making Files Permanently Open 885 
Extensions to Masterscope 886 

24.2.1 Dumping Masterscope’s Knowledge 886 
24.2.2 Enumerating the Masterscope Questions 887 
24.2.3 Finding Out About Everything 889 

24.2.4 Automatic Masterscope Database Creation 890 
The DECL Package 891 

TRANSOR: A LISP Translator 892 

Other LISP User’s Packages 892 

24.5.1 The Pattern Match Compiler 893 





Contents Xxix 


24.5.2 The Hash File Package 893 

24.5.3 EDITA: The Array Editor 893 

24.5.4 CJSYS: Access to the Operating System 893 
24.5.5 EXEC: A TENEX Executive in INTERLISP 893 
24.5.6 The NET Package 894 

24.5.7 FTP: The File Transfer Package 894 


25. THE PROGRAMMER’S ASSISTANT 895 


25.1 
iF 


25.3 
25.4 


25:9 


25.6 
25.7 


25.8 
25.9 


The Concept of Undoing 895 

LISPX: Type-In Evaluation 897 

25.2.1 A Definition for LISPX 898 

25.2.2 LISPX Macros 903 

25.2.3 User Processing of Input 90S 

Establishing a User Executive 907 

Undoable Versions of Destructive Functions 908 

25.4.1 Undoable Sets 908 

25.4.2 Replacing the Top-Level Value 913 

25.4.3. Undoing Mapping Functions 914 

25.4.4 Undoing Function Definitions 915 

25.4.5 Undoing the Putting and Removing of 
Properties 916 

25.4.6 Writing Your Own Undoable Functions 919 

Programmer’s Assistant Functions 919 

25.5.1 LISPX Support Functions 919 

25.5.2 Evaluating Expressions as if LISPXREAD 923 

25.5.3 Apprising the Assistant of Undoable Functions 924 

25.5.4 Substituting Undoable Versions 925 

25.5.5 Undoing Events 925 

25.5.6 Undoing When Errors Occur 928 

25.5.7 LISPX Printing Support 928 

Controlling Prompting 930 

The Reset Package 931 

25.7.1 Establishing a Reset List 931 

25.7.2 Restoring Your Environment 932 

25.7.3 Resetting Variables 934 

25.7.4 Resetting Expressions 935 

25.7.5 Establishing UNDO Information 936 

25.7.6 Structure of RESETFORMS 937 

Programmer’s Assistant Variables 938 

LISPX Statistics 939 

25.9.1 Printing LISPX Statistics 939 

25.9.2 Adding New Statistics 940 

25.9.3 Updating Statistics 940 

25.9.4 System Statistics 941 


XXX 


Contents 


26. MASTERSCOPE 943 


27. 


26.1 


Masterscope Concepts 944 


26.2 Interacting with Masterscope 944 
26.2.1 Analyzing Functions 944 
26.2.2 Erasing the Database 946 
26.2.3 Showing Structures 946 
26.2.4 Editing Functions 947 
26.2.5 Checking Sets 948 
26.2.6 Using CLISP in Masterscope 948 
26.2.7 Obtaining Help 949 
26.3 Specifying Sets 951 
26.4 Specifying Relations 955 
26.5 Specifying Paths 958 
26.6 Describing Function Behavior 960 
26.7 Masterscope Functions 965 
26.7.1 Entering Masterscope 965 
26.7.2 Determining Who a Function Calls 966 
26.7.3 Determining the Free Variables 967 
26.7.4 Getting and Setting Templates 967 
26.7.5 Defining Masterscope Synonyms 968 
26.7.6 Parsing a Relation 969 
26.7.7 Getting the Results of a Relation 969 
26.7.8 Testing a Relation 970 
26.7.9 Mapping Across a Relation 971 
26.7.10 Updating the Database 971 
26.7.11 Dumping the Masterscope Database 972 
THE RECORD PACKAGE 975 
27.1 Record Declarations 975 
27.1.1 Components of the Record Declaration 975 
27.1.2 Using the Record Declaration 977 
27.1.3 Translating the Record Declaration 978 
27.1.4 Record Subfields 979 
27.2 Creating a Record 979 
27.3 Testing for Records 982 
27.4 Manipulating Record Fields 983 
27.5 Records and Typed Records 984 
27.6 Property and Association List Records 986 
27.7 Array and Hashlink Records 987 
27.8 User Datatype Records 988 
27.9 Access Records 988 


27.10 Atom Records 989 


27.11 


Record Package Functions 990 
27.11.1 Editing a Record Declaration 990 
27.11.2 Obtaining a Record Declaration 990 


ee ae 


28. 


Contents XXxi 


27.11.3 Obtaining the Declarations of a Field 991 
27.11.4 Obtaining a Declaration’s Field Names 992 
27.11.5 Accessing or Replacing a Record Value 992 


27.12 User-Defined Datatypes 993 
27.12.1 Defining New Datatypes 994 
27.12.2 Fetching the Contents of an Object Field 995 
27.12.3 Replacing the Contents of an Object Field 995 
27.12.4 Creating an Instance of an Object 995 
27.12.5 Obtaining the Field Specifications 996 
27.12.6 Obtaining the Field Descriptors 996 
27.12.7 Identifying User Datatypes 997 
THE HISTORY PACKAGE 999 
28.1 Structure of the History List 999 


28.2 
28.3 


28.4 


28.5 


28.6 


Updating the History List 1003 

Event Specification 1003 

28.3.1 Event Addresses 1004 

History Commands 1006 

28.4.1 Re-executing Previous Expressions 1006 
28.4.2 Argument Substitution 1007 

28.4.3 Editing a Previous Event 1010 

28.4.4 Retrying an Event 1011 

28.4.5 Printing the History List 1012 

28.4.6 Undoing the Effects of Events 1012 
28.4.7 Correcting Errors via DWIM 1014 
28.4.8 Saving and Retrieving Events 1015 
28.4.9 Archiving Events 1017 

28.4.10 Forgetting Side Effects 1018 

28.4.11 Remembering Events 1018 

28.4.12 Printing Property Lists 1018 

28.4.13 Printing Atom Bindings 1019 
28.4.14 Analyzing Errors 1019 

28.4.15 Bypassing the Programmer’s Assistant 1020 
28.4.16 Preventing History List Recording 1020 
History Package Variables 1020 

28.5.1 LISPX History Macros 1020 

28.5.2 History Package Forms 1022 

28.5.3 The Archival Function 1023 

28.5.4 The Value of an Event 1024 

History Package Functions 1024 

28.6.1 Recording a History Event 1024 
28.6.2 Locating a History Event 1025 

28.6.3 Locating Events by Specification 1026 
28.6.4 Extracting a History Event 1027 
28.6.5 Obtaining an Event’s Value 1027 


XXXii 


Contents 


28.6.6 Changing a History List’s Timeslice 1028 
28.6.7 Searching the History List 1029 
28.6.8 Printing the History List 1029 


29. MISCELLANEOUS FUNCTIONS 1031 


30. 


29.1 


29.2 


29.3 


29.4 
29.5 
29.6 


29.7 


Chronometric and Counting Functions 1031 
29.1.1 Date and Time Functions 1031 

29.1.2 Clock Functions 1033 

System Functions 1034 

29.2.1 Exiting Interlisp 1034 

29.2.2 Obtaining the System Type 1035 
29.2.3 Obtaining the User Name 1036 
Performance Measuring Functions 1036 

29.3.1 Counting CONS Operations 1036 
29.3.2 Counting Page Faults 1037 

29.3.3 Timing an Expression 1038 
29.3.4 Breaking Down Performance by Function 1039 
Session Transcripts 1042 

Greetings 1043 

Directory Access Functions 1044 

29.6.1 Reading the File Directory 1044 
29.6.2 Manipulating File Directories 1044 
29.6.3 Connecting to Another Directory 1048 
Storage Management 1049 

29.7.1 Displaying Storage Usage 1049 

29.7.2 Gaining Space 1050 


THE INTERLISP EXECUTION ENVIRONMENT 1055 


30.1 


30.2 


30.3 


30.4 


Binding of Variables 1055 

30.1.1 Variable Types 1056 

30.1.2 Global Variables 1056 

Stack Structure 1057 

30.2.1 A Basic Frame Example 1057 

30.2.2 A Frame Extension Example 1058 

30.2.3 Stack Frames and Pointers 1059 

Stack Access Functions _ 1060 

30.3.1 Locating a Stack Frame 1061 

30.3.2 Obtaining and Changing the Frame Name 1063 
Variable Binding Functions 1064 

30.4.1 Obtaining Variables at a Stack Frame 1064 
30.4.2 Obtaining Variable Values at a Stack Frame 1065 
30.4.3 Scanning the Stack for Bindings 106S 

Stack Frame Operations 1066 

30.5.1 Distinguishing Real from Dummy Frames 1067 


31. 


30.6 


30.7 


30.8 
30.9 


Contents XXXiil 


30.5.2 Finding a Real Stack Frame 1068 

30.5.3 Scanning Frames for Atom Bindings 1068 

Evaluation in Other Frames 1069 

30.6.1 Evaluation in Other Contexts 1069 

30.6.2 Evaluating Expressions in an Access 
Environment 1070 

Manipulating Stack Pointers 1071 

30.7.1 Testing a Stack Pointer 1071 

30.7.2 Releasing a Stack Pointer 1072 

30.7.3 Clearing an Active Stack 1072 

30.7.4 Copying Stack Frames 1073 

Exiting from a Stack Frame 1073 

Operating on the Stack 1076 

30.9.1 Mapping Down the Stack 1076 

30.9.2 Searching Down the Stack 1077 


THE INTERLISP COMPILER 1079 


31.1 
31.2 


31.4 
315 


The Compiler Dialogue 1079 
Compilation Issues 1081 

31.2.1 Compiling NLAMBDA Functions 1081 
31.2.2 Declarations 1082 

31.2.3 Open Functions 1083 

31.2.4 Constants 1083 

31.2.5 COMPILETYPELST 1084 
31.2.6 Compiling CLISP 1084 
Compiler Functions 1085 

31.3.1 Compiling Functions 1085 
31.3.2 Compiling a Definition 1087 
31.3.3 Compiling Symbolic Files 1088 
31.3.4 Recompiling a File 1089 
Compiled Code 1090 

Compiler Error Messages 1091 


REFERENCES 1095 


INDEX 


1105 





INTERLISP 











Introduction 


LISP, as a language, has been around for about 25 years [mcca78]. It was origi- 
nally developed to support artificial intelligence (AI) research. At first, it seemed 
to be little noticed except by a small band of academics who implemented some 
of the early LISP interpreters and wrote some of the early AI programs. In the 
early 60’s, LISP began to diverge as various implementations were developed for 
different machines. McCarthy [mcca78] gives a short history of its early days. 

LISP, as a programming language, began to be widely used in the early 70’s. 
A number of organizations supported different dialects—BBN, MIT, Xerox 
PARC, UC Irvine, and others. In the middle 70’s, several people realized that 
conventional machines were not suitable for the efficient execution of LISP pro- 
grams. They began to develop a class of specialized processors known as LISP 
machines. By the early 80’s, renewed interest in AI and expert systems caused 
LISP to become more visible. Several dialects had been more or less standard- 
ized and a few companies (such as Xerox, Symbolics, and Lisp Machine) had 
entered into commercial production of LISP machines. Moreover, many people 
had discovered that LISP provided an excellent implementation language for 
some of the new ideas in software engineering. 

Today, LISP is being used for many applications other than AI programs 
(for example, see [elli80] and [levi80]), although it is still strongly associated 
with that discipline. In order to further its acceptance as a general purpose pro- 
gramming language, I have focused on describing a specific dialect of LISP— 
INTERLISP. I chose INTERLISP because there is a well-defined standard for 
it—namely, the INTERLISP Reference Manual [irm78, irm83]. Moreover, IN- 
TERLISP is available on the DECSystem 10/20 under TENEX and TOPS-20, 
on the VAX-11/780 under UNIX and VMS, on the IBM 30xx series under VM/ 
SP (available from Uppsala University, Sweden), and on the Xerox 1100 family 
of scientific information processors. Undoubtedly, more implementations will 
be available in the near future. 

This chapter will set the stage for an in-depth analysis of INTERLISP. In 
the first two sections, we motivate the choice of LISP and briefly explore some of 
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the available dialects. Sections 1.3 and 1.4 discuss the impact of LISP on the way 
we program and on the way we think about the architecture of software systems. 
Section 1.5 reviews the structure of the text. Section 1.6 discusses presentation 
issues. 


1.1 WHY LISP? 


Why should you choose LISP to implement a software system? For many rea- 
sons, as it turns out, some of which are physical (e.g., implementation issues), 
some of which are stylistic (e.g., programming issues), and some of which are 
conceptual (e.g., design or architectural issues). For the moment, let us concen- 
trate upon the physical reasons. f 

LISP offers many features and capabilities that would be/are difficult to 
provide in more traditional languages such as FORTRAN, PASCAL, and PL/1. 
I would like to review these with you and argue for the view that LISP can do 
them better. This does not imply that LISP is the best language for all applica- 
tions. There is no such language. But I do take the view that LISP should have a 
well-defined niche in your repertoire of programming languages. 

With this view in mind, the following paragraphs discuss some of the key 
ideas associated with LISP and contrast their implementation in conventional 
languages. 


1.1.1 Symbolic Computation 


Most programs compute on numbers. Conventional languages make the task of 
manipulating numbers quite easy. They may also be able to handle string or 
character expressions in an efficient manner. But, as AI research has shown, 
much computation at the human level is done on concepts—complex, structured 
representations of knowledge. Representation of knowledge is often the most 
critical element of the computational problem. There may be no intuitively obvi- 
ous way of selecting numeric codes to represent pieces of knowledge. Arbitrary 
encodings tend to obscure significant aspects of the problem, and make the task 
of programming, debugging, and testing very complicated. 

LISP was designed to allow the efficient, easy representation of symbolic 
expressions. We use lists in everyday life to keep track of things, so our personal 
experience should readily transfer to our use of lists in the computer. LISP essen- 
tially recognizes two basic data structures: atoms and lists. Atoms are just sym- 
bols—indivisible sequences of characters that have a meaning and a value. Lists 
are collections of atoms and/or lists (e.g., sublists). Lists are usually stored in 
the computer in a form similar to the way we see them on paper. The sequencing 
information of the elements of a list is explicitly stored with each list item. 

To manipulate symbolic knowledge, we represent it as a list of atoms and 
then perform various operations upon the representation. In many cases, the 
manipulation functions modify the structure of the list to add or subtract infor- 
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mation, to alter its structure, or to transform its contents. Examples throughout 
the text will demonstrate how these operations are performed. 

A number of languages have been built ‘‘on top of” LISP to provide sym- 
bolic algebraic manipulation, most notably, REDUCE2, developed by A.C. 
Hearn and colleagues at the University of Utah, and MACSYMA, developed by 
the MATHLAB Group at the Laboratory for Computer Science, MIT [math77]. 
Nicol [nico81] provides a definition of a simple symbolic differentiator for alge- 
braic expressions. 


1.1.2 Information Representation by Lists 


Information representation is a critical problem in designing a software system. 
It is particularly acute in Al programs and expert systems because the informa- 
tion structures themselves are manipulated. In LISP, most information is repre- 
sented as lists. Simple lists are composed of atoms while complex expressions 
have multiple levels of lists. This capability allows us to build very complex infor- 
mation structures without too much regard for addressing. By comparison, con- 
ventional languages rarely provide more than linear data structures, including 
two dimensional arrays and record structures as in PASCAL. 

Consider the representation of information concerning familial relation- 
ships between individuals. To represent the fact that Isaac is a child of Abra- 
ham, we may use the list 


(is-child-of isaac abraham) 


and the corresponding list to represent the relationship that Abraham is a parent 
of Isaac 


(is-parent-of abraham isaac). 


Other facts that might be represented about individuals include physical 
data such as gender, age, height, and so on, and other relationships, skills, or 
occupations. The power of the list representation allows us to capture all of this 
information in a single uniform data structure, the list. With a few simple primi- 
tive functions, we may begin to access and manipulate this information, and 
even build more powerful operators. 


1.1.3 Primitive Functions 


The essential kernel of LISP [moor79] is composed of a small set of primitive 
functions. Usually, these functions are hardwired to improve the efficiency of 
their execution. The composition of the kernel depends on the dialect. For ex- 
ample, the kernel of INTERLISP/370 is written in IBM assembly language 
while the kernel of INTERLISP-D is written in microcode. 


4 Introduction 


Most conventional languages do not have a primitive set of functions. 
Rather, the primitive functions reside in the underlying machine language. Con- 
ventional languages such as FORTRAN and PASCAL consist of statement types 
which represent simple methods for writing (possibly long) sequences of primi- 
tive functions. The source statements are translated into a sequence of machine 
language instructions by a compiler or an interpreter. The resulting executable 
program often bears no resemblance to the source program. 

John Backus [back78] argues for a simpler style of programming based on 
the concept of ‘functional programming.” It is interesting to note that func- 
tional programming corresponds to the basic mathematical theory of function 
composition carried over to the realm of programming language development 
and methodology. 

LISP provides an excellent example of the notions expressed in Backus’s 
paper. The minimal set of functions that we need in LISP to implement all other 
functions are CAR, CDR, and CONS, EQ, and a few predicates for testing data 
types. All other functions may be built from compositions of these elementary or 
primitive functions. Of course, most LISP systems define a much larger set of 
primitive functions for reasons of efficiency. Many of the functions that are de- 
scribed in this text for which definitions are given exemplify the notion of func- 
tion composition. 


1.1.4 Function Composition 


Proceeding from the kernel, LISP users create more complex functions by com- 
bining expressions containing primitive functions. The procedure is directly 
analogous to mathematical function composition. The beauty of this feature is 
that most of INTERLISP is written in LISP. One merely keeps building func- 
tions on top of functions to create more complex systems. 

We should think of LISP as a tool for building more powerful tools. Many 
systems designed for implementing artificial intelligence applications may right- 
fully be considered extended programming languages. Good examples include 
OPSS [forg81] developed by Charles Forgy at CMU and ROSIE [fain81, 82, 
haye82] developed by Frederick Hayes-Roth and others at the Rand Corpora- 
tion. 


1.1.5 Functions versus Data 


LISP possesses a singular advantage over most conventional languages, even 
those that are interpreted. This is that functions and data are represented in the 
same way. Conventional languages stress the separation of code and data as in- 
dependent entities. LISP emphasizes uniformity of representation—a single 
model, if you will. Thus, we can create a data structure as a list and treat the 
same data structure as an executable function definition or function invocation. 

The beauty of this approach is demonstrated in a technique known as proce- 
dural attachment [stee79]. You may define an object, nominally a frame, which 
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has slots for the attributes that describe or distinguish the object from others of 
its type. The value of an attribute may be an integer, atom, string, pointer to 
another object, or a procedure (e.g., a LISP function definition). The procedure 
may do anything a LISP function can do since it is a LISP function. Common 
uses of procedures are validation of data, transformation of data, asking ques- 
tions to obtain the values of other attributes, or performing some computation to 
instantiate another instance of the frame. You may operate upon the procedure 
definition as data, but execute it by applying EVAL to it. 


1.1.6 The EVAL Function 


The function EVAL serves a dual purpose in LISP. It is both the formal defini- 
tion of the language as well as an interpreter for its execution. That is, EVAL 
validates the syntax of the expressions presented to it for execution and verifies 
their semantics by invoking the requested functions. By comparison, most con- 
ventional languages separate the syntax validation, performed by the compiler, 
from the semantic verification, performed by the run-time monitor. 


1.2 LISP DIALECTS 


LISP has a long and rich history. There have been many dialects of LISP imple- 
mented on many different machines. McCarthy’s paper [mcca78] summarizes 
the initial development of LISP. As he notes, it began to rapidly diverge after a 
few years. Today, I think it is safe to say that there are two main dialects of LISP: 


1. INTERLISP, which runs on DECSystem 10/20 machines, DEC ma- 
chines, and Xerox 11xx Scientific Information Processors. A subset of 
INTERLISP, available from Uppsala University, Sweden, runs on IBM 
30xx processors under VM/SP. 

2. MACLISP, developed for the DECSystem 10/20 family by MIT’s Artifi- 
cial Intelligence Laboratory, which also runs on VAX-11/7xx machines. 
It, too, has spawned new machine architectures, principally Lisp Ma- 
chine’s LAMBDA machine and Symbolics’ 36xx family of LISP Work- 
stations. MACLISP has actually been superseded by CommonLisp, but 
the heritage remains the same. 


In this section, I will briefly review and note some of the other LISP dialects 
and their major differences. 


1.2.1 MACLISP/ZetaLisp 


MACLISP is a dialect of LISP that was developed at MIT’s Laboratory for Com- 
puter Science (formerly Project MAC). It runs on DECSystem-10/20s and VAX- 
11/7xx series processors. MACLISP is oriented to efficient numeric computa- 
tion within a symbolic environment. MIT’s Laboratory for Artificial Intelligence 
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pioneered the concept of personal computers running LISP through the develop- 
ment of the CONS (1976) and CADR (1978) Lisp machines. Subsequently, Sym- 
bolics [symb83] was formed to develop commercial Lisp machine products. 
Their first entry was the LM-2 which was a repackaged and enhanced CADR 
machine. In 1982, Symbolics announced the 3600, a fourth generation (they 
claim) Lisp machine. 

Winston and Horn [wins81] introduce MACLISP in the first part of their 
book. The second part gives numerous examples of LISP applications drawn 
from the AI arena. Charniak, Riesbeck, and McDermott [char80] provide an 
extensive discussion of MACLISP features in their book along with numerous 
examples of AI programs. 

There are major differences between MACLISP and INTERLISP. Winston 
and Horn note some of the most important differences are as follows: 


MACLISP does not distinguish case information; every character is 
translated to upper case on input. 

Several functions, such as SETQ, DIFFERENCE, and SOOT may 
take multiple arguments in MACLISP. 

MACLISP has only three types of function evaluation as opposed to four in 
INTERLISP. These are related as follows: 


MACLISP INTERLISP 
EXPR EXPR 
---- FEXPR 
LEXPR EXPR* 
FEXPR FEXPR* 


MACLISP uses the function DEFUN instead of DEFINEQ. The syntax is 
somewhat different. 

In MACLISP, MAPCAR’s arguments are (function) and <list). MAPCAR 
may also take multiple lists as its arguments where the (function) is applied 
to each element of each list. 


The last two arguments of PUTPROP are reversed in MACLISP. That is, 
the syntax of PUTPROP is 


(PUTPROP <atom) <value) <property)). 


MACLISP comments start with a ; which may occur anywhere within a 
program without affecting the execution of the program. 

Bitwise logical operations are performed by the function BOOLE in 
MACLISP with a numeric argument indicating which function is desired. 
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For their Lisp machines, Symbolics uses a variant of MACLISP known as 
ZetaLisp [wein81] which introduces the following new features [symb83]: 


A full range of data types 

Flexible function calling and multiple-value returns 

Stream-oriented input and output 

The Flavor System for object-oriented programming with message passing 
Macros for extending ZetaLisp syntax 


Predefined functions for sorting, hashing, linear equations, and matrix 
operations 


Multiple name spaces (packages) 


ZetaLisp will be compatible with CommonLisp, which has been developed 
by a consortium of academics and AI researchers along with considerable indus- 
try participation [stee84]. 


1.2.2 FranzLisp 


FranzLisp was developed at the University of California, Berkeley by John Fo- 
deraro [fode81]. It runs under Berkeley Unix BSD 4.1 and Eunice on VAX-11/ 
7xx series machines. It is being ported to a large number of microcomputers 
(primarily 16-bit machines) that also run BSD 4.1. FranzLisp is a subset of MA- 
CLISP. Lately, it has taken a development path that diverges from MACLISP 
through a series of enhancements designed and implemented by several universi- 
ties notably the University of Maryland and Carnegie-Mellon University. 


1.2.3 Portable Standard Lisp 


Portable Standard LISP (PSL) is a version of LISP being developed by the Utah 
Symbolic Computation Group. It has been described in a series of technical re- 
ports by Griss [gris81, gris82a, gris82b] and Marti [mart79]. PSL is written in a 
language called SYSLISP whose definition is given in Benson and Griss [bens81] 
and Griss and Hearn [gris81]. PSL was developed to support the porting of the 
REDUCE-2 symbolic algebraic manipulation system to a number of different 
machines. It is rumored that PSL will be the Lisp of choice for the Cray ma- 
chines. 


1.2.4 CommonLisp 


CommonLisp [stee84] is a collaborative effort of over 50 researchers and LISP 
programmers. Its authors claim that is a new dialect of LISP which is a successor 
to MACLISP, but which has been strongly influenced by Lisp Machine LISP, 
SCHEME, and less so by INTERLISP. 
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CommonLisp is intended to be a common LISP. That is, it should serve to 
unify the features of many of the successors to MACLISP that have been devel- 
oped for a variety of machines. Several groups have indicated that they will en- 
sure compatibility with CommonLisp once the standard reference manual is 
published. 

CommonLisp is intended to ensure portability of programs among a large 
number of machines by eliminating those features that cannot be implemented 
easily on any one of the machines. Some details are left to the implementors and 
some features are made optional. The goal is to ensure that programs adhering 
to the CommonLisp standard will be transferrable among machines as long as 
they contain no machine-specific features. 

CommonLisp is intended to define an internally consistent semantics for 
many standard LISP functions. Different implementations of LISP have treated 
variables in different ways which have resulted in different results when the pro- 
gram is moved from one machine to another (or even from one implementation 
to another, e.g., shallow versus deep bound INTERLISP systems). The refer- 
ence manual specifies one and only one semantic interpretation for each func- 
tion. 

CommonLisp follows the MACLISP tradition in emphasizing the power of 
system-building tools. Its designers envision, much like MACLISP and IN- 
TERLISP, that many user-level packages will be built on top of CommonLisp, 
but these are not part of the core specification. 

CommonLisp is designed to be efficient and stable. It is primarily compati- 
ble with MACLISP and its descendents/variants, but less so with INTERLISP. 

CommonLisp will unify a community of LISP programmers who have be- 
come quite fragmented by pursuing variations of MACLISP. The approach is 
laudable in that LISP, at least the MACLISP side, is one of the last languages to 
develop a coherent standard. I encourage you, when writing programs in IN- 
TERLISP, to pay careful attention to the CommonLisp constructs in the event 
that you want to translate your programs to that dialect. Having translated sev- 
eral programs from esoteric implementations of FranzLisp, I can assure you that 
the reverse translation is quite painful and labor-intensive (particularly to de- 
bug). 


1.3 LISP AS A PROGRAMMING ENVIRONMENT 


LISP may be considered from two viewpoints: first, as a programming environ- 
ment, and, second, as a conceptual environment. In this section, I will discuss 
LISP as a programming environment. In the next section, I will discuss it from a 
conceptual viewpoint. 

Different application domains place different requirements on the lan- 
guage(s) which may be used to write programs for them. Put another way, no one 
language is suitable for all applications. LISP was developed to support artificial 
intelligence (AI) research and has become the primary tool for developing pro- 
grams in that discipline. 
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This development has been neither circumstantial or serendipitous. LISP 
incorporates many ideas (indeed, it pioneered quite a few) that are now consid- 
ered to be essential elements of the professional programming environment. The 
following paragraphs summarize the major requirements for an AI program- 
ming language and discuss how LISP satisfies them. 


1.3.1 Multiple Data Types 


AI systems are generally large, complex programs. Many types of information 
are used and need to be represented within the program. A variety of data types, 
with associated operators, make it easier to encode and manipulate information 
within a program. INTERLISP provides numerous data types (see Chapter 2). 
One of the major features of INTERLISP is that any data type may be passed as 
an argument to a function. In most cases, the function must decide what it has 
and how to process it. In addition, you may also define your own data types (see 
Chapter 27) and utilize system functions to operate upon them. 

Lists, in one form or another, are the basic data structure used in AI pro- 
grams. Facilities for the efficient manipulation of lists are very important. Obvi- 
ously, INTERLISP satisfies this requirement as it is list-based. Chapters 3 and 6 
discuss the basic list processing primitives. 

As INTERLISP evolved, new data types were added to the language to in- 
crease its flexibility. Initially, INTERLISP supported only atoms, numbers (a 
special type of atom), and lists. Later, strings and arrays were added. Today, 
INTERLISP-D supports a number of basic data types such as bit maps and win- 
dows, to provide a powerful, window-oriented programming environment. This 
trend is significant because it makes INTERLISP useful as a general-purpose 
programming language. 

Defining new data types, such as relational tables for a database applica- 
tion, is relatively simple. Providing the associated support mechanisms may or 
may not be so simple depending on the complexity of the data structure. How- 
ever, the ability to develop a data type to meet your application needs without the 
artificial constraints that are often imposed by conventional programming lan- 
guages should allow you greater flexibility in your programming. 


1.3.2 Modular Programming 


To make large systems understandable, you must be able to decompose them 
into smaller modules that are both readable and maintainable. Segregation of 
functionality makes a system easier to manage when updates or modifications 
are required. Traditional languages may support two or three methods of de- 
composition. For example, FORTRAN has both functions and subroutines. A 
simple model is necessary to minimize sideeffects while making changes an easy 
task. INTERLISP uses a functional programming model where the basic units 
are functions. A system is just a collection of functions that invoke one another. 
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One decomposition strategy is to gather common useful patterns of state- 
ments into a package. These packages are not just abbreviations to save typing 
(like macros). Rather, they are abstractions which encapsulate higher level con- 
cepts that have meaning independent of their implementation. Once a package 
is constructed and properly tested, a programmer may use it directly, without 
regard for its internal details, because it corresponds to a concept or primitive 
notion that he uses to solve the problem. 

INTERLISP naturally supports the top-down programming methodology. 
You may define functions with stubs for functions to be called but defined later. 
The stubs are merely definitions of the functions which return NIL. When you 
are ready, you may use the editor to replace a stub by its full definition. The 
ability to incrementally build a system and test while you go has been called 
“‘prototyping”’ by certain programmers. You should note that it does not corre- 
spond to the classical top-down methodology espoused by most software engi- 
neers. 


1.3.3 Deferred Binding 


By binding, we mean the association of a value with a variable. For most AI 
programs, values are not known when the program is written, but become 
known as the program is executed. Conventional languages bind either at com- 
pile time or link time or, rarely, at execution time. INTERLISP binds at execu- 
tion time. For example, the size of a list need not be known until some function is 
applied to it. The same is true for the number and types of properties associated 
with a particular atom. Moreover, the structure of a list need not be known until 
it is operated upon by other functions. Indeed, the list may carry a description of 
its structure with it, a feature that is difficult to replicate in conventional lan- 
guages. The ability to break apart and put together lists with little or no regard 
for storage allocation is a feature that is rarely, if at all, found in more conven- 
tional languages. 


1.3.4 Interactive Development 


Most conventional languages are batch-oriented even though they may be ac- 
cessed from a time-shared environment. That is, a complete program unit is 
submitted for compilation, then loaded, and finally executed -- where each oper- 
ation is an independent activity. A few conventional languages such as BASIC 
and APL may be interactively executed. 

INTERLISP allows you to begin execution of programs that are only parti- 
ally written. At worst, attempting to execute a missing function generates an 
UNDEFINED FUNCTION error. More likely, it will cause a break (see Chapter 
20) and allow you to attempt to correct the problem. The correction may be as 
simple as correcting a misspelling of the function name or defining the body of 
the function. Returning from a break usually allows you to resume execution 
with no detrimental consequences to your environment. While this is not an 
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ideal way to develop a program, it does provide a convenient mechanism for 
testing a set of functions after they are written without having to complete the 
whole program. 


1.3.5 Flexible Control Structures 


A control structure determines the sequence in which program statements and 
functions are executed. INTERLISP supports the standard control structures 
such as conditional execution, case selection, and iteration. It also provides 
mechanisms for recursion (as an inherent language feature), and coroutines for 
parallel processing. Beyond these language-based features, we may define more 
sophisticated control structures that facilitate data-driven or goal-directed be- 
haviors. These control structures are usually embedded in expert systems. Three 
types of control structures that are often implemented in expert systems include 
[aiel83] 


Goal-driven (backchaining) 
Event-driven 
Model-driven 


Goal-driven strategies use a goal rule which invokes all rules whose conclu- 
sions are referenced by conditions in the goal rule. These rules invoke relevant 
rules in a chain until the rules to be executed reference only input data to the 
system. 

Event-driven strategies use a set of inputs to determine the invocation of one 
or more rule-sets. Executing these rule-sets generates new events which invokes 
more rules and so on until some conclusion is reached (e.g., no more events may 
be generated using the given rule-sets). 

Model-driven strategies match a current ‘‘state of the world” against prob- 
lem models to generate expectations. Expectations are events that stipulate in- 
puts to be looked for or requested from the user. As data are entered, the state of 
the world is updated until no more expectations may be generated (e.g., the 
model is complete within the given rule-sets). 

While these strategies are presented within the framework of expert sys- 
tems, I believe that they have general utility to other applications that might be 
written in LISP. Numerous books on AI, including Waterman and Hayes-Roth’s 
book [wate78], discuss various approaches to these control structures. 


1.3.6 Pattern Matching Facilities 


Pattern matching is a content-based selection strategy where the alternative to 
be executed is not known until run time. INTERLISP has been utilized to build 
a number of different types of pattern matching programs. Kornfeld [korn79] 
discusses a class of high level languages known as pattern-directed invocation 
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languages. Waterman and Hayes-Roth [wate78] edited a book that describes 
recent (at that time) work in pattern-directed inference systems. 

Patterns are merely templates for interpreting (or validating) otherwise arbi- 
trary data structures. For example, the pattern (A ? ? D) matches the data struc- 
ture (A B C D) but does not match the data structure (E ? ? D). Pattern match- 
ing allows us to retrieve a selected set of values of data structures (often called 
facts or assertions) from a larger collection by applying a pattern to them. Sim- 
ple pattern matchers are easy to build and are often given as introductory pro- 
gramming projects in LISP courses. Kornfeld describes a simple pattern 
matcher and demonstrates its actions with a few examples. 

In most databases, there are a number of facts that are not physically 
present in the database. More sophisticated pattern matchers have been devel- 
oped that can deduce or infer data from existing data given a set of patterns to 
work with. These pattern matches form the basis for production rule systems, 
many of which are described in Waterman’s book. Shapiro [shap79], Winston 
and Horn [wins81], and Charniak et al. [char80] all describe examples of simple 
deduction and inferencing systems based on pattern matching. 


1.3.7 Language Extensibility 


As I mentioned above, it is relatively easy to implement a very small kernel of 
LISP that allows you to “‘start’’ programmming fairly quickly. Rather quickly, 
you will find that you need additional functions or capabilities to implement 
problem solutions. Unlike most other languages, you will find that it is easy to 
extend the LISP language by merely introducing new functions. Many of the 
functions that you will encounter in this text have been written using basic LISP 
functions. That is, they represent extensions to the LISP language. The flexibil- 
ity and ease with which you may extend the language is perhaps its most power- 
ful feature. This means that you may tailor the form and features of the language 
to any class of users or any type of application. Once you begin programming in 
LISP with any regularity, you will find that you think in terms of language exten- 
sions rather than just implementing programs. 


1.4 LISP AS ACONCEPTUAL ENVIRONMENT 


Program design is a creative (some say artistic) process. Humans solve the prob- 
lems while computers implement the solutions. But the transformation from 
concepts to executable code is often a difficult and laborious process. The variety 
of problems to be solved means that there can be no standard recipes or mecha- 
nized processes to effect program design. For many problems, we do not know 
the nature of the solution although we may have a good idea of what the answer 
should be. The programming process then becomes one of exploration and ex- 
perimentation with solution techniques to elicit the essence of the problem. Of- 
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ten, the solution emerges along with the understanding of the problem. This 
method of programming is sometimes known as prototyping. 

LISP provides an environment that makes prototyping an effective means of 
exploring the solutions to problems. What we look for is the conceptual architec- 
ture of the problem, the steps to be taken to “solve” the problem, e.g., to pro- 
duce the right answer. Using conventional languages, we almost always must 
know the entire solution before we begin to write the program. With LISP, we 
can incrementally build and refine the solution as we explore different alterna- 
tives in the problem representation. 

Stefik et al. [stef82] note that design is the making of specifications to create 
objects that satisfy particular requirements. The problem that faces the pro- 
grammer is to develop the specifications for the program that produces a specific 
result. However, when the algorithm(s) and methods for solving the problem are 
not explicitly known, conventional languages offer no help in designing the pro- 
gram because they require us to have a complete conceptual architecture before 
coding. 

Stefik et al. note that there are five key problems associated with design: 


= 


. In large problems, a designer cannot immediately assess the conse- 
quences of design decisions. He must be able to explore design alterna- 
tives tentatively. 

2. A design will be constrained by many sources. Oftentimes, the con- 
straints are imposed by the features and capabilities of the language in 
which the solution will be implemented. 

3. To solve large problems, the designer must cope with system complexity 
by factoring the design into subproblems. He must also cope with inter- 
actions between the subproblems, since they are seldom independent. 
Consider the simplicity (after studying the LISP language) with which 
you may use top-down programming to decompose a complex problem 
into simpler, more manageable pieces. 

4. When a program becomes very large, it is easy to forget the reasons for 
design decisions. It is also hard to assess the impact of a change to a part 
of the program. While LISP does not provide any mechanism for captur- 
ing design decisions (other than comments), the ability to immediately 
test modifications to program segments and repeal (undo) those which 
do not lead to progress in the problem solution is a feature that is not 
often found in other languages (or is very difficult to perform). 

5. When programs are modified to reflect new design decisions, it is impor- 

tant to be able to reconsider different possibilities. Few languages have 

the inherent capability to maintain multiple versions of functions or to 
manage the structure of programs spread across one or more files. 

Through the File Package, INTERLISP provides this feature as a stan- 

dard capability. 
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1.5 STRUCTURE OF THE TEXT 


This text is divided into 31 chapters, a reference list, and an index. It loosely 
follows the organization of the INTERLISP Reference Manual [irm78, irm83]. 
However, I have taken the liberty of organizing the contents of individual chap- 
ters according to my own logical view even though this contravenes the IRM. 

Chapter 1 is an introductory chapter. It contains a short history of LISP and 
a discussion of different LISP dialects. LISP is examined in both the program- 
ming environment, as a language for implementing tools and systems, and in the 
conceptual environment, as a way of thinking about the functional architecture 
of systems. The remainder of the chapter contains this outline and notes con- 
cerning the presentation methods within the text. 

Chapter 2 discusses the basic data types provided by INTERLISP. These 
include atoms, lists, numbers, strings, and arrays. Operations on these data 
types are described in succeeding chapters. 

Chapter 3 discusses the primitive functions of INTERLISP. Most other 
functions can be built using these primitives. These functions are usually 
hardwired in machine language or microcode for purposes of efficiency. In gen- 
eral, most of the functions defined in this chapter and Chapters 4-13 are com- 
mon to all dialects of LISP although there may be a few discrepancies. You 
should note that INTERLISP is generally much richer in its primitive functions 
than most other dialects of LISP. 

Chapter 4 discusses the fundamental predicates. Predicates are a means of 
testing the condition of an S-expression or atom (or other datatype). A predicate 
returns either NIL (meaning false), T, or some non-NIL value (both of which 
mean true). Most of the fundamental predicates test whether their argument is a 
given datatype, whether the argument has a certain characteristic (e.g., even- 
ness or oddness) or whether two things are equal. 

Chapter 5 discusses logical connectives and predicates. A logical connective 
is either AND or OR. Logical predicates are EVERY, SOME, and their vari- 
ants. Note that it is possible to implement sophisticated control structures using 
the AND and OR functions. 

Chapter 6 discusses the list manipulation functions. These functions allow 
you to create and destroy lists, concatenate two or more lists, and copy lists. 
Together with the functions presented in Chapters 3 and 4, these functions usu- 
ally constitute the basic functions of the Lisp language. 

Chapter 7 discusses property lists and functions for manipulating them. 
Property lists are attached to atoms. A property list is a list of (name) <value) 
pairs which may be thought of as descriptors or characteristics of the atom. 

Chapter 8 discusses function definition and evaluation. A function is a spec- 
ification for operating upon an atom, list, or other datatype or data structure. 
INTERLISP provides several methods for defining and using functions. 

Chapter 9 discusses atom manipulation and the rules for creating atoms. 
Atoms are the elementary information carriers in INTERLISP. 
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Chapter 10 discusses string manipulation functions. Strings represent an 
unusual datatype in that they are neither atoms nor lists. 

Chapter 11 discusses arrays, including hash arrays, and their associated 
functions. It describes how to create 2-D arrays, known as matrices. 

Chapter 12 discusses the mapping functions. Mapping is a technique for 
iterating (applying) a function over multiple instances of a datatype. 

Chapter 13 discusses the basic arithmetic functions, both integer and float- 
ing point. Special functions, including some statistical functions, are also de- 
scribed. 

Chapters 14 and 15 describe the functions associated with input and output. 
Rather more information is provided in these chapters than the novice program- 
mer needs to know. Judicious reading will help you decide what is immediately 
necessary. Mastery of the input/output functions is essential to becoming a com- 
petent INTERLISP programmer. 

Chapter 16 discusses file management functions. Unlike conventional lan- 
guages, which depend on the operating system or system utilities for file man- 
agement [kais82], INTERLISP incorporates a set of file management functions 
into its environment. Depending on the environment, these functions may or 
may not interface with external operating system functions. 

Chapter 17 describes the features and capabilities of the File Package. At 
one level, the File Package may be viewed as a sophisticated source code control 
system similar to that provided by the Programmer’s Workbench in UNIX 
[dolo78}. 

Chapters 18 and 20 discuss error handling and debugging procedures. 
Whenever an error occurs, INTERLISP allows you to inspect the state of your 
environment, modify it, and (hopefully) resume your computation. 

Chapter 19 discusses the LISP editor. The editor understands the structure 
of S-expressions and function definitions, so it is known as a structure editor. It 
operates upon S-expressions in a manner that is (usually) guaranteed to preserve 
the balance of parentheses. Novices may begin with a few simple commands. 
Experienced users have a wealth of powerful, flexible commands at their beck 
and call. 

Chapter 21 discusses the process of advising a function. Advising allows you 
to modify the interface between a function and its environment, whether or not 
the function is called from another function. You may ‘“‘intercept” the function 
before or after it is executed. 

Chapter 22 discusses the DWIM (Do What I Mean) facility. DWIM pro- 
vides an error correction facility for simple errors associated with spelling, and a 
facility for handling simple structural errors. DWIM receives control before the 
error mechanisms described in Chapters 18 and 20. 

Chapter 23 discusses Conversational LISP (CLISP). CLISP allows you to use 
English-like phrases in place of some of the normal INTERLISP constructs. 
CLISP makes LISP programs appear more like a conventional language and 
hence more readable. 
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Chapter 24 discusses a number of LISP users packages. These are packages 
or subsystems contributed by various INTERLISP users that extend the capabil- 
ities of the system in various ways. As INTERLISP-D continues to spread 
throughout the AI and programming communities, more packages are being 
developed and submitted to Xerox all the time. Xerox has incorporated some of 
the most useful and practical packages directly into the INTERLISP-D system. 

Chapter 25 discusses the Programmer’s Assistant. The Programmer’s Assis- 
tant performs simple error correction, including spelling correction, on the more 
obvious errors committed by a user when typing in a function or S-expression to 
the system. 

Chapter 26 discusses Masterscope, a utility for managing aspects of the code 
development process. Masterscope allows you to keep track of the modules or 
functions that have been developed, to examine their interactions, and to main- 
tain (to a limited extent) subsets of the functions comprising your program. 

Chapter 27 discusses the Record Package. The Record Package effectively 
implements a data-access programming technique that relieves you of the bur- 
den of worrying about storage management. You determine the data structures 
and how they are to be used. INTERLISP translates these declarations into calls 
to primitive functions when it executes your programs. 

Chapter 28 discusses the History Package. Together with the Programmer’s 
Assistant, the History Package provides a flexible environment for developing 
source code. The History Package effectively maintains an audit trail of your 
interactions with INTERLISP at the top level. You may retry, correct, or undo 
erroneous expressions, and you may create new commands within the package. 

Chapter 29 is a catchall chapter for functions that don’t seem to have a logi- 
cal fit elsewhere. This is really not a fair interpretation of the utility of these 
functions, but they are too few to warrant a chapter of their own. Included are 
the clock functions, greetings, storage management, and a function for regain- 
ing space when your virtual memory becomes full. 

Chapter 30 discusses the structure of the underlying INTERLISP environ- 
ment. INTERLISP dynamically binds values to variables using a stack mecha- 
nism. The stack is accessible to you through stack manipulation functions or 
through the Break Package. 

Chapter 31 discusses some aspects of the process of compiling. Once: you 
have debugged your programs to the point where you think they can run without 
major errors, it is often advisable to compile the code in order to gain increased 
efficiency and performance. 


1.6 COMMENTS ON THE TEXT 


The structure of this text reflects some of my personal biases about how to 
present material to a technical audience. It is important that you, the reader, be 
aware of these biases as you read (or peruse) this and succeeding volumes. 
One major bias is that readers understand and (hopefully) learn more about 
the subject by seeing many concrete examples of the things that are being talked 
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about. You will find this text replete with examples for the many functions and 
features that are discussed. In addition, I show how to develop new functions for 
capabilities that are not currently provided by the baseline version of IN- 
TERLISP (although this is changing as a result of Xerox’s continued develop- 
ment and enhancement of the language and programming environment). 

Another bias is that people learn more about how things work by seeing how 
functions and programs are put together. Thus, in many cases, I have tried to 
show the basic code that is used to implement a feature. The code is often a 
skeletal representation of the functions necessary to implement the full capabil- 
ity. Some functions are merely suggested while others are developed in full. 

Where functions take multiple arguments, I have used a tabular format to 
show the structure of the function and describe its arguments. I feel this makes it 
easier to refer to the meaning and/or usage of arguments that may be given to a 
function. 

I have tried to follow several conventions in this text to make it easy to read. 
These conventions are listed below: 


When I reference an INTERLISP function, whether in text or in an 
example, it will always be capitalized. 

Arguments to INTERLISP functions, whose skeletons are given in the text, 
will always be entered in lower case, except when upper case is specified 
explicitly in the INTERLISP Reference Manual [irm78,irm83]. 

When I refer to arguments of INTERLISP functions in text, I will capitalize 
the names of the arguments so that their usage is clear. 

When I define a function, I will capitalize the primitive functions used, but 
generally show the function definition in lower case. I believe this highlights 
the distinction between the basic functions and those that may be developed 
“ton top of’? INTERLISP. I also believe that it improves readability of the 
text. You should note, however, that INTERLISP always operates in upper 
case. 

I have consistently tried to use the symbol + to indicate the prompt 
throughout the text. This symbol is normally used only on INTERLISP-D. I 
have represented it as two characters since most terminals (and typesetters) 
do not have the left arrow as a standard symbol. Please be aware that left 
arrow has several other meanings as well in INTERLISP. 
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After you have defined a problem, one of the first tasks that you face in captur- 
ing the problem solution in executable code is how to represent the data required 
to solve the problem in a form manipulable by the computer. In doing this, you 
are constrained by the data types and structures provided by the programming 
language. In most conventional programming languages, these are fixed by your 
choice of language. In INTERLISP, a set of basic datatypes is provided with the 
language, but you are also provided with the ability to extend these through vari- 
ous mechanisms inherent in the language. 

INTERLISP provides a wide variety of datatypes. The primitive datatypes 
are lists and atoms. Other datatypes have been provided to increase the effi- 
ciency of INTERLISP and remedy the problems of representation of certain 
types of data structures. This chapter will describe the basic datatypes used by 
most INTERLISP programmers. Extensions to these datatypes will be discussed 
in chapters that describe the functions for manipulating the datatypes. 


2.1 LITERAL ATOMS 


A literal atom is the most basic datatype of INTERLISP. A literal atom is some- 
thing that stands for itself. Thus, every literal atom created in the INTERLISP 
system must be unique. If two literal atoms have the same name (called the prin- 
name or pname), then they are the same identical atom. This means that these 
atoms will always have the same address in memory. 

Atoms play the part of variables in INTERLISP. Different programming 
languages treat the notion of variables in different ways depending on how the 
variable is stored in memory and how values are bound to it. Variables allow you 
to write programs in which the actual values of data items are not known until 
the program is executed. However, by implication, the values associated with 
variables in a programming language are always finite because of the limitations 
of the computer. 
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The “‘attributes”’ of a variable describe how the variable will be treated in a 
program. Among the attributes that may be associated with a variable are 


The permitted range of values 
The scope of its name 

How and when it is created 
The type of the variable 


A simple model of a variable might appear as: 


Unlike conventional programming languages, INTERLISP variables do not 
have an explicit type associated with them. Rather, the variable takes on the type 
of its current value whether it is a array pointer, integer, string, or another atom. 

The “‘value representation” describes the form that the value of the variable 
takes in memory. Often, the value representation is a function of the underlying 
hardware. However, list representation, even though an elementary datatype, is 
a data structure imposed on top of (or extending) the essential machine hard- 
ware. 

INTERLISP extends this simple model with additional information. Each 
literal atom consists of the following components 


a pname (print name) 

a value 

a property list (see Chapter 7) 

a function definition cell (see Chapter 8) 
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2.1.1 Pnames 


A pname is the name of the atom as it appears when printed by one of the IN- 
TERLISP printing functions. Pnames are not directly accessible by the user. 
The representation of a pname in memory is dependent on the particular imple- 
mentation. The maximum length of a pname is a 127 characters for IN- 
TERLISP-10 and 255 characters for INTERLISP-D. 

Examples of atoms include the following 


BEN FRANKLIN COUNTRY 
1.2567 751 


2.1.2 Value Cells 


A value cell is a storage area assigned to hold the value of an atom. A value cell 
always contains the top-level value of an atom. When an atom is initially created, 
the value cell contains the atom NOBIND which indicates that no explicit value 
has been bound to the atom. Atoms may also have values bound in stack frames 
as the result of PROG expressions and function calls. 

A value cell is created for an atom when 


The atom is referenced in a SETQ function 
The atom is used as the argument to a function 
The atom is used as a PROG variable (see Section 3.7) 


Values are really pointers to other INTERLISP objects rather than the ac- 
tual values themselves. 
Binding is discussed in Chapter 30. 


2.1.3 Property Lists 


Each atom may have a value. The value may be a number, another atom, a list, 
or an address of some other structure, such as an array. But atoms really repre- 
sent (in most cases) complex objects; that is, they stand for something. These 
object usually have a multitude of characteristics. Most conventional languages 
require you to define and manipulate several complex data structures in order to 
fully define an object. LISP, however, allows you to attach a property list to an 
atom. A property list is a list of descriptors and their associated values which 
serves to further define or describe the object represented by the atom. 


2.1.4 Function Definition Cells 


Each atom has an accompanying function definition cell, e.g., a cell whose con- 
tents are a list that defines a function of the same name. Thus, in INTERLISP, 
atoms may have both values and actions associated with them. INTERLISP dis- 
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tinguishes between these two usages by the appearance of the atom name in a 
list. 


2.1.5 Creating Atoms 


There are several ways to create atoms in INTERLISP: 


by assigning a value to a literal atom’s pname 

by packing a sequence of characters to form an atom pname 
by making an atom 

by asking the system to generate a temporary symbol 


Setting the Value of an Atom 

An atom may be created by assigning a value to a literal atom. This is the most 
commonly used method of creating atoms in INTERLISP. As an example, con- 
sider the assignments 


(setq boy 'john) 
(set 'boy 'john) 


Both of these statements have the effect of assigning the value ‘‘john’”’ to the 
atom whose name is “‘boy.’’ The difference results from the operation of the 
function SETQ (see Section 3.8). If this is the first time that ‘‘boy’’ has ever 
occurred in an INTERLISP program, when the function (either one) is executed, 
the atom “‘boy”’ will be created and assigned the value ‘‘john.’’ By created, we 
mean that INTERLISP allocates memory for it, defines the underlying data 
structure, and places JOHN in the value cell of BOY. 


Creating an Atom via PACK 
An atom may be created by packing a list of atoms to form the PNAME of a new 
atom. Typically, the list consists of atoms each of which is a single character. 
Consider the list (b al t imo re). When this list is given to PACK (see 
Section 9.3.1) as an argument, it concatenates the individual characters into a 
PNAME that represents a single atom. In this case, the single atom is BALTI- 
MORE. Of course, the list does not have to be composed of single characters as 
in the following case: 


(PACK '(tom—jones) ) 
which yields the atom TOM-JONES. 
Making an Atom 


An atom may be created by the function MKATOM which operates on strings 
(see Section 9.2.2). For example, the function call 
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(MKATOM 'john-jones'') 
would create the atom JOHN-JONES. 


Generating a Temporary Atom 
Atoms may be created by INTERLISP at your request. INTERLISP provides the 
function GENSYM to create atoms of the form xnnnn where x is a character and 
the n’s are digits. Typically, atoms generated in this way are used for temporary 
storage within an INTERLISP program. 

To create an atom using GENSYM, you may either specify the character or 
NIL as in the following examples: 


(GENSYM 'B) which produces an atom such as B0102 
(GENSYM) which produces an atom such as AQOO1 


A counter is maintained internal to INTERLISP. The value of this counter 
is used to determine the digits which are appended to the character passed to 
GENSYM. If no character is specified by the user, INTERLISP automatically 
assumes the character A. 


2.1.6 Binding Variable Values 


Binding is the act of associating a value representation with a variable. There are 
two notions of binding that you must understand in INTERLISP: 


1. Bound versus unbound atoms 


A "bound" variable has a legal value assigned to it. An 
unbound variable has no value assigned to it (not even 
NIL). If you use a variable in an expression, INTERLISP 
attempts to evaluate it, finds that it does not have a 
value, and issues the error message "U.B.A." for '"UnBound 
Atom". Atoms created without values (such as in PROG 
declarations) will have the atom NOBIND placed in their 
value cell. NOBIND is a special atom within the INTERLISP 
system which indicates 'no value." A predicate, BOUNDP, 
allows you to determine whether or not an atom has a 
value bound to it. 


2. Global (free) versus local atoms 


INTERLISP programs (systems) consist of a set of 
functions that are linked together by calls from one 
another. Variables may be global or local within a set of 
functions. A local variable is one which is defined 
within a function and is used only within that function. 
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Typically, local variables are declared by the LOCALVARS 
declaration or by appearing in a PROG header. Global 
variables are variables defined in one function and used 
(freely) in one or more other functions. The INTERLISP 
name space is a one-level name space. Thus, any atom 
defined by a SETQ, GENSYM, etc. is known to all 
functions. 


Another type of binding is the time when storage is allocated to the variable. 
Most conventional languages and systems will bind variables to memory loca- 
tions at one of three times: 


Compile time 
Link edit time 
Execution time 


INTERLISP dynamically allocates storage to all atoms at execution time. 
This allows memory to be used efficiently in the computation process at some 
expense to performance in managing the memory. Currently, one of the critical 
problems with INTERLISP (and other LISP dialects) is that once atoms are cre- 
ated they cannot be destroyed in the same session. Variables created in a PROG 
header are temporary place holders on the stack. All other atoms are allocated 
specific storage locations and become a “‘permanent”’ part of your INTERLISP 
environment. Methods for managing your environment to save only the relevant 
information are discussed in Chapter 17. 


2.1.7 Variable Typing and Declaration 


Most conventional languages require you to declare your variables before you 
use them. That is, you must ‘‘announce”’ the name and type of a variable to the 
compiler in a declaration statement before the variable name is used in an exe- 
cutable statement elsewhere in the program. The “type” of a variable deter- 
mines . 


The set of values it may assume 
The set of operations to which it may be subjected 


For example, declaring a variable to be a STRING (or CHAR) specifies its 
storage representation and the permissible operations upon it. Thus, I can con- 
catenate two strings, but I cannot add them together. Each TYPE in a conven- 
tional language has a set of operations that are checked by the compiler at com- 
pilation. The compiler generates error messages if you attempt to violate the type 


of a variable. Note that the type of the variable is (usually) permanent through- 
out the program. 
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INTERLISP (and other LISP dialects) do not require you to declare or type 
a variable. A variable is declared when it is referenced for the first time. Its type 
is determined when you make an assignment of a value to the variable. Thus, the 
“type” of a variable may change during the execution of a program as different 
values are assigned to it. Type checking is performed when the value of a vari- 
able is utilized since a function cannot know the type of the variable’s value until 
it has actually referenced it. 

The notion of typing leads to the concept of ‘‘constants,”’ e.g., data items 
whose value cannot be changed. INTERLISP (and other LISP dialects) do not 
utilize the notion of constant except in the following cases 


The atom T has a fixed value that may not be changed. 
The atom NIL has a fixed value that may not be changed. 
Numbers (both FIXP and FLOATP) have values that may not be changed. 


In some systems, NOBIND is represented as an atom whose value may not 
be changed. 


Thus, aside from these few cases, any atom may be assigned any value at any 
time during execution. 


2.2 NUMBERS 


All programming languages include the capability to manipulate numeric data. 
Even in nonumeric data processing, there is a need to use numbers as counters, 
system parameters (such as line length), and control variables in a computation. 
Unlike mathematics, however, the classes of numbers that we use in program- 
ming languages are finite. That is, the range of values of a class of numbers is 
constrained by the physical attributes of the machine (such as register size). 
INTERLISP supports two types of numbers: integers and floating point 
numbers. Every number is an atom. They differ from literal atoms in that they 
do not have property lists, value cells, function definitions, or explicit pnames. 


2.2.1 Integers 


An integer is represented as a string of digits preceded by an optional sign (either 
‘*—? or +") and followed by an optional ‘‘Q’’. If the Q is present, the number 
will be interpreted as an octal (base 8) number. INTERLISP/370 allows you to 
enter hexadecimal numbers by entering an optional ‘‘—”’ or “‘+”’ followed by an 
‘at sign” (@) followed by a string of hexadecimal digits (0... A... F). 

Integers may be either ‘‘small”’ or “‘large.”’ Small integers fall into the range 
[ —65536,65536] while large integers fall in the range [—2**32,2**32]. For IN- 
TERLISP/370, the range of small integers is [—2**23,2**23] which fits into the 
24-bit address field used by IBM Series 370 machines. 
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Integers may be created by PACK and MKATOM since they are atoms, as 
in the following example: 


(PACK 
(LIST 3 4 5)) 


will create the integer 345. In a similar fashion, we could also specify the follow- 
ing code: 


(PACK 
(LIST 7 7 'Q)) 


which would yield the integer 63. In this case, the ’Q means that the integer is 
77Q (i.e., 77 base 8 or 63 base 10). 

Small integers are given special storage in INTERLISP in order to increase 
the efficiency of the system. Large integers are not. Thus, the user should be 
careful when testing the values of integers. Two small integers are always guar- 
anteed to have the same representation. Two large integers may have the same 
value but not the same address in memory. Thus, if you use the EQ function on 
the two integers, they may not be equal. Instead, use the function IEQP or 
EQUAL to test the equality of two integers (see Section 13.2). 


2.2.2 Floating Point Numbers 


A floating point number corresponds to a real number in traditional languages 
such as FORTRAN. A floating point number is read or written as a (possibly) 
signed integer, followed by a decimal point followed by another sequence of dig- 
its. The digits following the decimal point are known as the fraction or mantissa. 
A floating point number may be optionally followed by an exponent designated 
by E followed by a (possibly) signed integer in the range —39 through +38. 

Whether the fraction or the exponent is used is at your discretion, but one 
must be present to distinguish a floating point number from an integer. 

Floating point numbers may be created during input (via READ), by apply- 
ing FLOAT to an integer, and by PACK or MKATOM. 

Floating point numbers are printed by the system using format controls 
specified by the function FLTFMT. 


INTERLISP-D Convention 
Floating point numbers are currently stored in single precision using the IEEE 
“single’’ mode of 32 bits. 


INTERLISP/370 Convention 
If the floating point number contains six or fewer digits, it is stored as a single 
precision number. If it contains more than six digits, it will be stored as a double 
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precision number. Floating point numbers in the range 1E—3 to 1E6 will be 
printed without an exponent; otherwise they will be printed with an exponent. 


2.2.3 Complex Numbers 


A complex number is a generalization of the real number that is introduced in 
mathematics so that all polynomial equations with real coefficients may have 
solutions. A complex number is composed of two parts: a real part and an imagi- 
nary part. Most conventional languages, developed for numeric data processing, 
support the notion of complex numbers. For example, FORTRAN has a type 
declaration COMPLEX which results in a specific storage representation and set 
of operations upon complex numbers. INTERLISP (and other LISP dialects) do 
not support complex numbers. However, it is not difficult to create a data struc- 
ture to provide this capability. Chapter 13 will dicuss some ideas concerning the 
implementation of complex numbers. 


2.2.4 Conversion between Numeric Classes 


In mathematics, integers are a ‘‘subclass’’ of the real numbers. In computer 
systems, because integers and floating point numbers must be represented dif- 
ferently in storage, integers cannot be considered a subclass of floating point 
numbers. Thus, we need a set of conversion routines that allow us to convert 
data from one representation to another. However, conversion introduces inac- 
curacy in our numeric representations due to precision of representation and 
“‘roundoff”’ errors in arithmetic computations carried out by the machine. 


2.3 LISTS 


The second basic datatype within INTERLISP is the list. A list is a collection of 
zero or more components which may be atoms or other lists. A list with no com- 
ponents is often called the empty or null list. Lists may have atoms as their com- 
ponents, other lists as their components, or a mixture of both. A list is usually 
viewed as an ‘“‘ordered”’ collection of components. The components may be inte- 
gers, floating point numbers, strings, array pointers, or other data objects. 

The format of a list begins with a left parenthesis (. It is followed by any 
number of atoms or other lists and is terminated by a right parenthesis ). Thus, a 
very simple list would appear as (MARYLAND) where the atom’s name is 
MARYLAND. Of course, the simplest list that we may write is ( ) which is a 
representation for the null list. 

Examples of more complex lists include 


(MARYLAND VIRGINIA WEST-VIRGINIA) 


where individual atoms are separated by blanks and 
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(MARYLAND (CAPITOL ANNAPOLIS) (GOVERNOR HARRY-HUGHES) ) 
which consists of an atom and two sublists represented, respectively, by 


(CAPITOL ANNAPOLIS) 
(GOVERNOR HARRY-HUGHES) 


In general, lists are known as S-expressions where the S stands for ‘“‘sym- 
bolic.” Thus, the generic form of a list is given by 


(S-expression[1] S-expression[2] ... S-expression[n]) 


The simplest form of an S-expression is the dotted pair which consists of two 
atoms, respectively the CAR and CDR. A dotted pair usually appears as 


(apple . orange) 
((the rain in spain) . (stays mainly in the plain)) 


The trend, today, is to discourage the use of the “dot notation” because it 
does not correspond to the recent implementations of LISP. I mention it here 
only so that you know of its existence. 

The key to INTERLISP is parentheses. Lists are well-formed when pairs of 
left, (, and right, ), parentheses balance in an expression. Many problems arise 
in writing INTERLISP expressions and functions because parentheses do not 
balance. Thus, a cardinal rule is to always check your parentheses (or use soft- 
ware that does so for you—see the INTERLISP Users Packages). 

Lists may be created, destroyed, and manipulated in many interesting ways. 
We can create lists using CONS, LIST, or APPEND. We can access elements of 
lists using CAR, CDR, and their variants. We can manipulate them using 
RPLACA, RPLACD, ASSOC, MEMBER, and many other functions. Chapters 
3 and 6 describe many of the primitive functions that operate upon lists. 

We may constrain the full generality of these list structures in order to create 
other types of data structures. Some of these data structures include 


Stack A list in which all insertions, deletions, and accesses are 
made at one end of the list, known as the “top” of the 
stack. 

Queue A list in which additions can be made only at one end and 
deletions only at the other end. 

Deque A “double-ended” queue in which insertions, accesses, or 


deletions may be made at either end of the list. 


2.4 Arrays 29 


Knuth [knut68], Horowitz and Sahni [horo82], and Aho, Hopcroft, and UI- 
Iman [aho83] all discuss the theory, representation, and manipulation of these 
data structures. 


2.4 ARRAYS 


Arrays are one of the most familiar data structures in programming, perhaps 
because we use tables (arrays) to store information in our everyday activities. An 
array is an ordered set of elements of the same type. Each array has dimensional- 
ity, the number of subscripts that must be used to reference an individual item 
within it. Vectors are one-dimensional arrays while matrices are two-dimen- 
sional arrays. 

Vectors are often represented in the following form: 


Vim (04s VOs W395 V45 eas WN 


Matrices are often represented in the following form: 


all al2 ... aiN 
a2l ‘d22: si ASN 


aMi aM2 ... aMN 


An array is represented as a block of contiguous storage of arbitrary length. 
Array storage (in INTERLISP-10) is divided into three sections 


A header 
A section containing unboxed numbers 
A section containing pointers 


The header of an array contains descriptive information. Its format depends 
on the implementation. 

The unboxed number section stores numbers, either real or floating point. 
The pointer section contains INTERLISP-10 pointers that allow an array to rep- 
resent a collection of objects other than numbers. The size of the unboxed and 
pointer regions may range from 0 to the size of memory. Arrays are explained in 
greater detail in Chapter 11. 
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INTERLISP/370 Convention 
INTERLISP/370 represents the internal format of an array as follows: 


word 0 | length | 
1 | reserved | | 

2 | pointer address | 

3 | reserved | 

4 | numbers | | 

| | 

j | pointers | 

| | 

Ba | 


where the length of the block is given by 
16 + 4 * ARRAYSIZE 


The value 16 is derived from four bytes times four words of header informa- 
tion. Each number and/or each pointer also consumes four bytes. 


INTERLISP-D Convention 

INTERLISP-D has extended and refined the concept of arrays to fit its new im- 
plementation. In this implementation arrays contain only one “type” of data so 
there is no division of an array into partitions. Data types that may be stored in 
arrays include BIT, BYTE, WORD, FIXP (integers), FLOATP (floating point 
numbers), and POINTER. Arrays may have either a 0-origin or a 1-origin; the 
default is 1 as required by the TENEX implementation. 


2.4.1 Dimensionality 


The dimensionality of an array should be chosen to meet the needs of the prob- 
lem to be solved. Most languages allow you to specify up to three dimensions 
(each of different size) for an array. Some languages allow an unlimited number 
of dimensions. Most applications usually require no more than three dimen- 
sions. Unfortunately, INTERLISP supports only one-dimensional arrays at the 
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current time. In Chapter 11, we describe a method for implementing two-dimen- 
sional arrays using the one-dimensional structures provided by INTERLISP. 

The bounds of an array’s dimensions correspond to the lower and upper 
limits on the values of its subscripts. Many languages allow these limits to be any 
pair of integers such that the lower limit is less than the upper limit. INTERLISP 
requires that all subscripts have a lower limit (the origin) at either 0 or 1. The 
lower limit must be the same for all dimensions of the array. This allows both 
conventional mathematical numbering as well as the practice that is more com- 
mon in most conventional programming languages. 


2.4.2 Specification and Creation of Arrays 


Several pieces of data must be known to create an array (following the IN- 
TERLISP-D convention) 


The type of the elements 

The size or bound of the array 
The origin of the array 

The initial value of each element 


Arrays may only be created via the ARRAY function (see Section 11.1). Ele- 
ments may only be accessed via ELT and set via SETA. Unlike most conven- 
tional languages, INTERLISP allows you to specify an initial value that is as- 
signed to every element of the array when it is created. Arrays are referenced in 
INTERLISP by passing the address of the array to various functions that can 
manipulate them. 


2.4.3 Hash Arrays 


A second type of array is the hash array. It is an array that provides a linkage 
between one INTERLISP data type, the hash item, and another data type, the 
hash value. A hash array consists of a number of cells defined when you create 
the hash array. To enter an item into the hash array, you provide both a key and 
its associated value. A hashing function (internally defined) is applied to the key 
to generate a cell index. A hash link, consisting of a pointer to the hash item and 
a pointer to the hash value, is placed in the cell. You obtain an item from a hash 
array by specifying its key. 

When a hash array is seven-eighths full, INTERLISP assumes it to be com- 
pletely full. Attempts to add new items to the hash array will result in an error. 
However, INTERLISP does provide a mechanism for handling these overflow 
conditions which is explained in Section 11.3.5. 

Hash arrays are used by several of the INTERLISP packages. A notable 
instance is CLISPARRAY which is used by the CLISP package (see Chapter 23). 
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2.5 STRINGS 


A string is a collection of alphanumeric characters that has a literal value but 
does not represent a data item. The number of elements in a string is called the 
length of the string. Strings are demarcated by pairs of ‘* (double-quotes). Any 
characters except ‘‘ and % may appear within a string. Clearly, “ may not be 
included because it is the marker for a string. % has the special meaning of 
escape which is discussed in more detail in Chapter 14. 

A string is not a fundamental datatype since it cannot be read directly by 
READ. Strings are created by the function MKSTRING, and manipulated by 
the functions SUBSTRING and CONCAT. Strings may be read in from external 
files via the function RSTRING. 

A number of different operations may be defined for strings. The two most 
important operations are concatenation, where we join together two strings to 
make a new one, and substring, where we extract a segment of a string to make a 
new one. Most other string operations can be defined as sequences of these two 
operations. 

It is also frequently necessary to scan strings for a specific character or se- 
quence of characters. Scanning is utilized in many important applications (text 
processing, message decoding, etc.). It includes 


Searching for delimiters 
Searching for words in order to construct indices and concordances 


Searching for character patterns in messages in order to recognize sections 
of the message 


Scanning may be programmed with the substring access function, but most 
implementations of INTERLISP provide a search function to improve the effi- 
ciency of the scanning process. 

Internally, a string is stored in two parts: a string pointer and the sequence 
of characters that compose the string. A string pointer consists of the length of 
the string and the address at which the string begins. INTERLISP-10 and IN- 
TERLISP-D both support 32,767 characters as the maximum length of strings. 


INTERLISP/370 Convention : 
INTERLISP/370 supports only 256 characters as the maximum length of a 
string owing to machine instruction characteristics. 


2.6 RECORDS AND USER DEFINED DATATYPES 


The datatypes described in the previous sections are inherent features of a basic 
INTERLISP system. Users, however, may extend the classes of datatypes by 
adding new list structures. INTERLISP formally captures this notion in the Re- 
cord Package which is described in Chapter 27. 
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A record is an object that has a formal description. Each record has a fixed 
number of fields. The record may be thought of as an object template which is 
used to create instances. A user may access and replace the contents of individ- 
ual fields within an instance of the record. The individual elements of a record 
need not all be the same datatype. This notion is captured in many conventional 
programming languages in various forms. 

Elements of a record are accessed by their name. You may reference the 
whole record or any part of it. Individual fields of the record may themselves be 
records (subrecords). Since a record description is a template for a data struc- 
ture (e.g., an S-expression), we may lay the template over any S-expression. 

In addition, you may define new datatypes with complex structures via the 
function DECLAREDATATY PE (see Section 27.7). The primary difference be- 
tween records, which also use the datatype functions, and your own datatypes is 
that the File Package and other subsystems “‘know” about records and how to 
formally treat them. In most cases, you will have to provide your own functions 
for manipulating, saving, and restoring your datatypes. 


2.7 FILES 


Files are not strictly an INTERLISP datatype. However, most programs require 
a mechanism for specifying long term storage of data in an organized manner. 
The File Package supported by INTERLISP, which interfaces with the host op- 
erating system, provides a method for the user to retrieve, store, and organize 
external data. 

INTERLISP treats files as a byte stream much like Unix. You may open a 
file and read from or write to it using various input and output functions. A 
hierarchy of capabilities is provided by the File Package which allows you to treat 
files in various ways. Since INTERLISP functions are just S-expressions, func- 
tion definitions, data, and file descriptors (e.g., commands for creating the file) 
may be intermixed in a single file. This feature is unlike conventional program- 
ming languages which require the separation of the data and program code. 

When a symbolic file is written by the File Package, a file map is placed at 
the end of the file. A file map contains the names and addresses (as byte offsets 
from the beginning) of objects within the file. Many of the File Package func- 
tions use the file map to extract objects and their values from a symbolic file. 

One special type of file is written by INTERLISP—a file containing com- 
piled code. Compiled code is a combination of low-level function calls and ma- 
chine language instructions. Its format and contents depend on the implementa- 
tion. Aside from a few examples, we will not discuss this type of file in this text 
because it is implementation dependent. 
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INTERLISP, as a symbolic processing language, encourages the use of ‘‘func- 
tional programming” concepts. Functional programming emphasizes the use of 
well-defined functions that “operate” on data structures or objects—either sys- 
tem defined or user defined. The previous chapter discussed some of the basic 
data structures provided by INTERLISP. This chapter explores the primitive 
functions that you may use to begin constructing more complex functions. Most 
primitive functions are “‘hardwired”’ in assembly language or microcode for rea- 
sons of efficiency. 


3.1 TAKING LISTS APART: CAR AND CDR 


INTERLISP provides two functions for taking lists apart; that is, decomposing a 
list into its constituent elements. These are CAR and CDR. The names are mne- 
monic and are rooted in the historical implementations of INTERLISP’s prede- 
cessors. The earliest version of LISP was implemented on an IBM 704 computer 
in assembly language. The 704 word had two key fields: the address field and the 
decrement field. The CAR pointer of an atom was contained in the address field 
while the CDR pointer was contained in the decrement field. 

CAR returns the first element of a list. CDR returns the remaining elements 
of a list (which may be NIL) after the first element. 

The generic formats of these two functions are 


Function: CAR 

# Arguments: 1 

Argument: 1) a nonempty list, LST 
Value: The first element of the list. 
Function: CDR 
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# Arguments: 1 
Argument: 1) a nonempty list, LST 


Value: The remainder of the list after the 
deletion of the first element. 


CAR always returns the first element of its argument, if it is a list. Suppose 
we have created the following list using SETQ: 


«+-(SETQ presidents '(adams hayes monroe nixon ford) ) 
(adams hayes monroe nixon ford) 


When we apply CAR to this list, it returns the value 


«(CAR presidents) 
adams 


which is the first element of the list. 
CDR always returns the remainder of a list minus its first element. If we 
apply CDR to PRESIDENTS we obtain the result 


«(CDR presidents) 
(hayes monroe nixon ford) 


Note that CDR always returns a list as its result if its argument is a valid list. 
CAR may return either an atom or a list depending on the type of the first 
element in its argument. For example, if we construct the following list: 


<(SETQ presidents-parties 
'((kennedy democrat) (nixon republican) ) ) 


and then apply CAR to it, we obtain the result 


“(CAR presidents-parties) 
(kennedy democrat) 


which is a list of two atoms. CAR returned a list because the first element of its 
argument was a list. 
If CAR is applied to an atom, it returns an error message as a result: 


«(CAR 'kennedy) 
ARG NOT LIST 


However, CDR applied to an atom returns NIL since we assume that the 
empty list is pointed to by the CDR portion of an atom. 
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«(CDR 'kennedy) 
NIL 


Both CAR and CDR may be applied to the empty list which is represented 
either by the atom NIL or the list ‘(). In this case, both functions will return the 
result NIL: 


«(CAR NIL) 
NIL 
“(CDR '()) 
NIL 


CDR operates normally on lists of one element by returning the value NIL 
meaning there are no more elements in the list. For example, applying CDR to 
the list (LINCOLN) yields 


—(CDR '(lincoln) ) 
NIL 


because this list has only one element. Thus, an implied /ast element of every list 
is the null or empty list. 


3.1.1 CAR/CDR Combinations 


Lists are rarely so simple as those given above. Often, we build fairly complex 
structures that have multiple levels of elements. Processing these lists with CAR 
and CDR functions can be difficult if we need certain elements quite often. 

Consider the list PRESIDENTS-PARTIES given above. How do we obtain 
the first element of the second sublist? One way is to take the CDR of the list, 
and then take its CAR: 


<-(CAR (CDR presidents-parties) ) 
nixon 


or 
+(SETQ parties-temp (CDR presidents-parties) ) 
(nixon republican) 
<(CAR parties-temp) 


nixon 


Both of these methods are unwieldy. Too many CARs or CDRs used to dis- 
sect a list will result in code which is obtuse and incomprehensible. Fortunately, 
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INTERLISP provides us with a method of ‘abbreviation’ for combinations of 
these common functions. ; 
The general form of a combination is 


(CxxxxR <some-list-argument) ) 


where each ‘x’ represents either an A or an D. Most LISP systems will support all 
combinations (a total of 30) of the four-letter abbreviations. 
We can rewrite the forms to retrieve the first element of the second sublist as 


<(CADR presidents-parties) 
nixon 


We analyze such forms by reading from ‘right-to-left’ in the function 
name. This form says: take the CDR of the argument, and then take the CAR of 
the result. Note that INTERLISP does not return the intermediate result, which 
is the CDR of the argument, but only the final result that we seek. 

Another example is given by the following list, which is slightly more com- 
plex: 


<-(SETQ electoral-year-votes 
(LIST '(1952 eisenhower 442) 
'(1956 eisenhower 457) 
'(1960 kennedy 303) 
'(1964 johnson 486) 
'(1968 nixon 301) 
'(1972 nixon 520) )) 


which represents the election/president/electoral votes for recent elections. 
Let us ask how we get the name of the winner of the election of 1956? Of 
course, we know the answer is EISENHOWER because we can see it in the list. 
But how do we dissect the list to retrieve it? 
We might reason as follows: 


(1956....) is the second sublist of the list. 


It is also the first element of the CDR of the list so we know that we can use 


«(CADR <list)) 
(1956 eisenhower 457) 


EISENHOWER is the second element of a list, so following the same reasoning 
as above, we can produce 
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(CADADR <list)) 
eisenhower 


which is the desired result! 
Note that we could have written this out as: 


«(CAR (CDR (CAR (CDR (list))))) 
eisenhower 


A few more examples should be sufficient to demonstrate the various combi- 
nations: 


«-(CADDDR electoral-year-votes) 
(1964 johnson 486) 


«-(CDADR electoral-year-votes) 
(eisenhower 457) 


«(cddddr electoral-year-votes) 
((1968 nixon 301) (1972 nixon 520)) 


Note that the list has too many elements to extract the last sublist using a 


combination form. To get the electoral votes for NIXON’s second victory, we 
must use: 


<-(CADDDR (CDDDDR electoral-year-votes) ) 
520 


Here is a table of the first few combinations of CARs and CDRs that are 
commonly used in INTERLISP programs. 


CAR/CDR Combinations 


Abbreviation Extended Form 

(CAAR <list)) (CAR (CAR <list))) 
(CADR <list)) (CAR (CDR <list))) 
(CDAR <list)) (CDR (CAR <list))) 

(CDDR <list)) (CDR (CDR <list))) 
(CADAR <list)) (CAR (CDR (CAR <list)))) 

| | 
(CADDR <list>) (CAR (CDR (CDR <list)))) 


Here are some examples of how these abbreviations might work on the list 
given above: 


— (CAAR electoral-year-votes) 
1952 
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«(CADR electoral-year-votes) 
(1956 eisenhower 457) 


«+(CDAR electoral-year-votes) 
(eisenhower 442) 


«+(CDDR electoral-year-votes) 
((1960 kennedy 303) ..... ) 


3.2 PUTTING LISTS TOGETHER: CONS, LIST AND APPEND 


In order to take lists apart, we need some way to have put them together in the 
first place! The three functions discussed in this section permit you to create lists 
in various ways. Before proceeding to a discussion of these functions, let us note 
that we can create lists using the SETQ function. 

Remember that we said that SETQ assigns a value to an atom which is its 
first argument. This value may also be a list. Using SETQ, of course, the second 
argument is unevaluated (see Section 3.8), so the list will be typed exactly as you 
wish it to appear as the value of the atom. For example, 


<(SETQ alist '(apple orange plum pear cherry lemon) ) 
(apple orange plum pear cherry lemon) 


sets the value of ALIST to be the specified list. If we now ask for the value of 
ALIST, we should receive 


“alist 
(apple orange plum pear cherry lemon) 


We briefly mention SETQ here so that it may be used in examples in the 
following sections. 


3.2.1 CONS: Constructing Lists 


CONS is the list construction function. It takes the form 


Function: CONS 
# Arguments: 2 
Arguments: 1) any atom or list, EXPRESSION 
2) any list, LST 
Value: A list whose CAR is the value of the first 


argument and whose CDR is the value of its 
second argument. 
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CONS takes two arguments, one of which is a list, and puts them together to 
form a new list. The first argument of CONS is always the element to be added to 
the second argument, which is always a list. The first element is always attached 
to the front of the second to form the new list. The first argument may be either 
an atom or a list. For example, consider the following sequence of INTERLISP 
statements: 


«-(SETQ subject 'john) 

john 

«-(SETQ predicate '(is big)) 
(is big) 


«-(CONS subject predicate) 
(john is big) 


The result of the CONS is to form a new list having a value that is a combina- 
tion of its two arguments. The first argument may also be a list. Consider the 
following example: 


«(SETQ subject '(the boy)) 
(the boy) 


“(CONS subject predicate) 
((the boy) is big) 


Note that since the first argument is a list, the first element of the new list 
must also be a list! This is not exactly what we wanted though. Rather, we 
wanted our new list to look like this: 


(the boy is big) 


To accomplish this, we need to dissect the first argument, and then CONS 
the pieces together. The following statement achieves this effect: 


<(CONS (CAR subject) 
(CONS (CADR subject) predicate) ) 
(the boy is big) 


Because NIL represents the empty list, we may use it as the second argument 
of CONS. CONSing an atom and NIL together creates a list of a single element. 


Consider this example: 


«(CONS subject NIL) 
((the boy) ) 
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We may read this as: take the CONS of the value of “‘subject’”’ and NIL, and 
return a list of them. This is a list of the list (the boy) and the empty list which is 
never represented when we print out lists unless the list value is the null list. 
Thus, it is possible to construct a list as follows: 


«(CONS NIL NIL) 
(NIL) 


Because this construct is frequently used, many LISP dialects define a func- 
tion, NCONS, which CONSes a single argument with NIL. It takes the form 


Function: NCONS 

# Arguments: 1 

Argument: 1) an S-expression, EXPRESSION 

Value: The value of the argument CONSed with NIL. 


What happens if the second argument to CONS is not a list but an atom? CONS 
still executes, but it forms a data structure known as a dotted pair. A dotted pair 
is a CONS cell with pointers to two atoms—a degenerate list form. We may rep- 
resent it graphically as follows: 








L° PRR? fe Pee 
Vv vV 
X x 


and display it, when printing the values, as 
(X «. ¥) 


Notice the “‘dot” separating the two atom names whence the notion of the 
dotted pair. 

The concept of dotted pair often causes LISP novices much trouble. I will 
only mention dotted pairs briefly in the remainder of this text, usually to point 
out where they may cause problems for users. Touretzky [tour84] and Siklossy 
[sik176] both give adequate explanations of dotted pairs. 


3.2.2 LIST: Making Lists 


INTERLISP provides a very useful primitive function for creating a list from any 
number (indefinite) of arguments. This function is called LIST. 
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The format of the LIST function is shown below 


Function: LIST 

# Arguments: 1-N 

Arguments: 1-N) S-expressions, EXPRESSION[1] 
EXPRESSION[N] 

Value: A list of the values of its arguments. 


LIST takes each of its arguments in turn and places them in a list. It is a 
nospread function. For example, consider the following statement: 


«(LIST 'the 'boy 'is 'big) 
(the boy is big) 


Note that the result is the same as one we previously created with multiple 
SETQs and CONSes. We may think of LIST in the following way: 


(LIST <argument)) = (CONS <argument) NIL) 


Both of these statements will give the same result. The utility of the LIST 
function becomes apparent when we want to create much larger and more com- 
plex lists. For example, using CONS, we would have to write the following state- 
ment to create the list (the boy is big): 


(CONS 'the 
(CONS 'boy 
(CONS 'is 
(CONS 'big NIL)))) 


So, we may think of LIST as a shorthand notation for writing multiple CON- 
Ses to create a list. The beauty of LIST is that it take any number of arguments 
and gathers them up into a list. Note that it evaluates its arguments as it pro- 
cesses them for inclusion into the resulting list. The following example shows 
how we might create the list for presidential elections that we used in a previous 
example: 


(LIST 
(LIST 1952 'eisenhower 442) 
(LIST 1956 'eisenhower 457) 
(LIST 1960 'kennedy 303) 


Note that each argument to LIST becomes an element of the new list. In the 
example above, one argument is the S-expression (LIST 1956 ‘eisenhower 457). 
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Each of the arguments 1956, ‘eisenhower, and 442 becomes an element of a list 
created by that LIST function. Because the form (LIST 1952 ‘eisenhower 442) is . 
an S-expression, it is evaluated when it is encountered in the list of arguments to 
produce a value that is then included in the resultant list. Its value, of course, is 
(1952 eisenhower 442). 

Note that LIST with no arguments returns NIL, but (LIST NIL) returns 
(NIL). 

We said that LIST may take any S-expression as an argument. We have seen 
where one of those S-expressions forms a list when evaluated. Other examples of 
LIST to consider include 


«(LIST '(apple orange) '(plum cherry) ) 
((apple orange) (plum cherry) ) 


Here, the arguments are lists that are passed to LIST. If the argument is 
already a list, LIST embeds it as a sublist within a list. For example, 


«(LIST '(apple orange) ) 
((apple orange) ) 


But, if you do not want it to be embedded as a sublist, then you must test to 
see if the argument is already a list before applying LIST to it. Fortunately, IN- 
TERLISP provides a function that performs this chore for you, MKLIST. It 
takes the form 


Function: MKLIST 

# Arguments: 1 

Argument: 1) an S-expression, EXPRESSION 

Value: A list containing the value of EXPRESSION. 


MKLIST makes a list from the value of its argument. If EXPRESSION is 
already a list or NIL, MKLIST merely returns the value of EXPRESSION. Oth- 
erwise, it applies LIST to the value of EXPRESSION. For example, 

«-(MKLIST 'cherry-pie) 

(cherry-pie) 


«+ (MKLIST) 
NIL 


*-(MKLIST (LIST 1952 'eisenhower 442)) 
(1952 eisenhower 442) 


We might define MKLIST as follows (although I haven’t told you how to 
define functions yet): 
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(DEFINEQ 
(mklist (expression) 
(COND 

((OR 
(NULL expression) 
(LISTP expression) ) 
expression) ) 

(T 


. (LIST expression) ) ) 


3.2.3 APPEND: Concatenating Lists 


A function that also creates new lists is APPEND. Unlike LIST, however, AP- 
PEND takes an indefinite number of lists as its arguments and returns a list by 
copying the lists to the new list. The generic format for invoking APPEND ap- 
pears as follows 


Function: APPEND 

# Arguments: 1-N 

Arguments: 1-N) lists, LST[1] ... LST[N] 
Value: A list of the S-expressions of the 


individual lists. 


Note that (APPEND) and (APPEND NIL NIL) both return NIL. Consider 
the following example: 


<-(SETQ subject '(the boy)) 
(the boy) 


«(SETQ predicate '(is big)) 
(is big) 

«(APPEND subject predicate) 
(the boy is big) 


Note that two individual lists have been combined into one list. Compare the 
two functions to see how they work: 


«(LIST subject predicate) 
((the boy) (is big)) 


«(APPEND subject predicate) 
(the boy is big) 
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We see that after LIST is executed, the two arguments still retain their iden- 
tity whereas, after APPEND is executed, they are merged into one list. We call 
this top level copying because APPEND takes the top level values and concate- 
nates them together giving a new list. 

APPEND is usually implemented as a “hardwired”’ primitive to provide effi- 
cient execution since it is so frequently used. We can, however, write APPEND 
as a recursive function using just CONS and CDR (see Chapter 8 for a discussion 
of function definition). 


(DEFINEQ 
(APPEND (a-list b-list) 
(COND 
((NULL a-list) b-list) 
(T 
(CONS 
(CAR a-list) 
(APPEND (CDR a-list) b-list)))) 
)) 


but this does not copy B-LIST. It merely links the cells of B-LIST to those of A- 
LIST. Thus, a change to the new list created by the concatenation may also 
change B-LIST. It also works upon only two lists, e.g., it is a very simple defini- 
tion of APPEND. 

An alternative definition copies the top level elements of each argument. It 
is defined as follows: 


(DEFINEQ 
(append lst 
(PROG (value x temp y z) 
(SETQ temp (CAR lst)) 


(COND 
((AND 1st 
(NULL (CDR 1st)) 
(LISTP temp) ) 
(SETQ lst (CDR lst)) 
(GO loop4))) 
loop1 
(COND 


((NLISTP 1st) 
(RETURN value) )) 
(SETQ temp (CAR 1st) ) 
(SETQ 1st (CDR l1st)) 
(COND 
((OR 
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(NLISTP 1st) 
(NLISTP temp) ) 
(* 


Only the last one of more 
than one argument is not 
copied. 


) 
(GO loop2))) 
loop4 
(SETQ z 
(SETQ y 
(CONS (CAR temp) 


(CDR temp) ))) 
loop3 


(SETQ temp (CDR temp) ) 
(COND 
((LISTP temp) 
(SETQ y 
(RPLACD y 
(CONS (CAR temp) 
(CDR temp) ))) 
(GO loop3))) 
(SETQ temp z) 
loop2 
(COND 
((LISTP x) 
(RPLACD (SETQ x (LAST x)) 
temp) ) 
(T 
(SETQ value (SETQ x temp)))) 
(GO loop1)) 
)) 


APPEND will also work on arguments that are not lists. However, the data 
structures that are produced involved dotted pairs. Consider the following exam- 
ples: 


<-(APPEND 'kennedy 
(LIST 'johnson 'nixon 'ford 'carter)) 
(johnson nixon ford carter) 


«(APPEND (LIST 'johnson 'nixon 'ford 'carter) 
'reagan) 
(johnson nixon ford carter . reagan) 
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< (APPEND 
(APPEND (LIST 'johnson 'nixon ' ford) 
'carter) 
(LIST 'reagan) ) 
(johnson nixon ford reagan) 


< (APPEND 
(APPEND (LIST 'johnson 'nixon 'ford) 
'carter) ) 
(johnson nixon ford . carter) 


Note that APPEND is modifying the values of the CDR pointers in the 
CONS cells when it combines lists. 


3.2.4 Creating (NIL) 


Sometimes, we will find it useful to create a list containing the NIL list. This list 
takes the form (NIL). We can create this list in two simple but elegant ways using 
the primitive functions CONS and LIST. 

With CONS, we merely say 


« (CONS) 
(NIL) 


which returns (NIL) because both of its argument are NIL. 
With LIST, we can merely say 


«-(LIST NIL) 
(NIL) 


where the second argument is an implied NIL that is treated as the empty list 
because that is what LIST expects. 

Note that APPEND cannot be used to return (NIL) because it operates upon 
lists. Thus 


+ (APPEND) 
NIL 


“(APPEND NIL NIL) 
NIL 


3.3 PHYSICAL STRUCTURE REPLACEMENT: RPLACA AND 
RPLACD 


In Section 2.4, we discussed the structural representation of lists using cells. 
This provided a convenient way of thinking about lists as collections of pointers 
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to values as well as boxes for holding values. Using this model, whenever we 
created a result from a function so far, we have always allocated new cells to hold 
the result. This approach can be quite expensive, both in terms of execution 
efficiency and in consumption of free memory. 

INTERLISP provides us with two functions that allow us to physically mod- 
ify a list without allocating new cells. These functions, RPLACA and RPLACD, 
allow us to replace the contents of the CAR or the CDR portions of a list cell, 


respectively. 
3.3.1 Replacing the CAR Cell 


RPLACA (RePLAce CAr) allows us to replace the CAR portion of a list cell. 
RPLACA takes the following form 


Function: RPLACA 

# Arguments: 2 

Arguments: 1) an S-expression resolving to an atom, 
ATM 


2) an S-expression, EXPRESSION 


Value: The new value of the literal atom after 
the replacement has been performed. 


Suppose we have created a list of the following form: 


<(SETQ good-idea '(apple pie is tasty)) 
(apple pie is tasty) 


We can change the type of pie by using RPLACA to change the CAR portion 
of the first list cell (e.g., the one containing “‘apple’’) as follows: 


«-(RPLACA good-idea 'cherry) 
(cherry pie is tasty) 


Note that INTERLISP allocates no new cells to hold the result but merely 
changes the pointer to the atom APPLE to the pointer to the atom CHERRY. 
We say that RPLACA “‘smashes”’ the CAR value of the CONS cell. We can dia- 
gram this as follows: 
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good-idea 
| 
| 
v 
I Kec? 2 II fcc? 2 I Cc?) 
| | | | 
|\ | | | 
pes Vv v Vv 
| \ pie is tasty 
e- % 
| \ 
| \ 
v \ 
apple 
v 
cherry 


where # indicates that the pointer to APPLE has been broken (e.g., no longer 


exists). 
Errors may occur when we give RPLACA bad arguments. For example, we 


cannot RPLACA NIL. Consider the statement 


<(RPLACA NIL (anything) ) 
ATTEMPT TO RPLAC NIL 


except for the form (RPLACA NIL NIL) which has no effect at all: 


«(RPLACA NIL NIL) 
NIL 


If we attempt to replace the CAR portion of something that is not a list, 
INTERLISP returns the error ARGUMENT NOT LIST. Consider the state- 


ment 


«-(RPLACA 'apple (anything) ) 
ARGUMENT NOT LIST 


3.3.2 Replacing the CDR Cell 


In a similar fashion, RPLACD (RePLAce CDr) replaces the pointer to the CDR 
portion of a list cell. RPLACD takes the following form: 
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Function: RPLACD 

# Arguments: 2 

Arguments: 1) an S-expression evaluating to a literal 
atom, ATM 
2) an S-expression, EXPRESSION 

Value: The new value of the literal atom after 


the replacement has been performed. 


Using the list GOOD-IDEA defined above, we can use RPLACD to create a 
list that has as its value (apple tarts are tough). 


«-(RPLACD good-idea '(tarts are tough) ) 
(apple tarts are tough) 


The following diagram shows how this is done: 


good-idea 
| 
| 
Vv 
| | [eo] | deed} dE deer dE 
ak | | | 
| \ v Vv Vv 
Vv \ pie is tasty 
apple \ 
\ 
| 
| 
Vv 
| be est ot ieee 
| | | 
| | | 
Vv Vv v 
tarts are tough 


where # indicates that the pointer from the CDR portion of the CONS is broken. 

Using RPLACD can be dangerous for a number of reasons. If you change 
the pointer to a group a cells to which nothing else points, those cells are lost. For 
example, the cells comprising the list (PIE IS TASTY) are pointed to by the 
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CDR portion of GOOD-IDEA By replacing that pointer, we have no knowledge 
of the address of the first cell of that list. Thus, the cells are allocated, but we 
have no way to access them again during the remainder of the INTERLISP ses- 
sion. Too many mistakes in this fashion causes memory to be consumed at a 
prodigious rate. One indication that memory is disappearing is a more frequent 
occurrence of garbage collections. 

Another problem that you may encounter is creating circular lists. Circular 
lists may be good or bad, depending on your application’s requirements. In most 
cases they are bad. We can create a circular list by causing the CDR portion of a 
list cell to point to the beginning of the list. For example, consider the following 
statement: 


«-(RPLACD (CDDDR good-idea) good-idea) 
. an infinite list... 


causes the CDR portion of the last cell of GOOD-IDEA to point to the first cell 
of the list. 

Errors may occur if we give RPLACD bad arguments. For example, we can- 
not replace the CDR portion of NIL: 


<(RPLACD NIL (anything) ) 
ATTEMPT TO RPLAC NIL 


except that INTERLISP allows us to say (RPLACD NIL NIL) which has no ef- 
fect at all: 


<-(RPLACD NIL NIL) 
NIL 


If we attempt to RPLACD something that is not a list, INTERLISP returns 
the error ARGUMENT NOT LIST. For example, consider 


<-(RPLACD 'apple <anything)) 
ARGUMENT NOT LIST 


3.3.3 Replacing the CAR and CDR of a Cell 


INTERLISP provides two functions to replace the contents of a node (e.g., an 
atom) without changing the atom’s name: RPLNODE and RPLNODE2. 
RPLNODE takes the form 


Function: RPLNODE 
# Arguments: 3 


3.4 Preventing Evaluation 53 


Arguments: 1) an atom, ATM 
2) an S-expression, EXPRESSION-A 
3) an S-expression, EXPRESSION-D 


Value: The name of the atom. 


RPLNODE (RePLace NODE) replaces the CAR and CDR pointers of the 
atom’s CONS cell without changing the name of the atom or creating a new 
CONS cell. 

We might define RPLNODE as follows: 


(DEFINEQ 
(rplnode (atm expression-a expression-d) 
(RPLACA atm expression-a) 
(RPLACD atm expression-d) 
atm 


)) 


RPLNODE2 also replaces the contents of an atom’s CONS cell by extracting 
the CAR and CDR portions of an S-expression. It takes the form 


Function: RPLNODE2 
# Arguments: 2 


Arguments: 1) an atom, ATM 
2) an S-expression, EXPRESSION 


Value: The name of the atom. 
We might define RPLNODE2 as follows: 


(DEFINEQ 
(rpnode2 (atm expression) 
(RPLACA atm (CAR expression) ) 
(RPLACD atm (CDR expression) ) 
atm 


)) 


3.4 PREVENTING EVALUATION 


In programming languages, we need to differentiate between a symbol that 
stands for something (i.e., a variable) and a literal (i.e., a symbol whose value is 
itself). Numbers are literals. Atoms are variables. 

When we use atoms in INTERLISP statements, we assume the atom has a 
value. What we want to manipulate is the value of the variable, not the name of 
the variable. For example, 
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(IPLUS x y) 


means add the value of X to the value of Y and return the result. 

Arguments are usually passed to INTERLISP functions using the call-by- 
value method. That is, what the function “‘sees”’ is not the name of the variable, 
but its value. So, in evaluating the statement above, what IPLUS sees are the 
values of the variables X and Y. INTERLISP evaluates the two arguments to 
determine their values and passes these values to the function. 

Sometimes we do not want arguments evaluated before they are passed to a 
function. In Chapter 8, we shall see one method of preventing evaluation in the 
way in which certain types of functions (called NUAMBDA functions) are de- 
fined. Another way is to QUOTE the argument so that its literal value is passed 
rather than attempting to evaluate it for a value. 

Suppose we want to test the equality of two values. First, we may represent 
them as the values of atoms. For example, 


<(SETQ x 'apples) 


apples 

<(SETQ y 'oranges) 
oranges 

<(EQUAL x y) 

NIL 


because the two values are not equal. We could directly specify the value 
ORANGES instead of assigning it to a variable as follows: 


«(EQUAL x 'oranges) 
NIL 


If we had attempted to execute 


“(EQUAL x oranges) 
UBSA. 
oranges 


because INTERLISP expects ORANGES to be the name of a variable that has a 
value. By quoting ORANGES, we tell INTERLISP that it should pass the literal 
value ORANGES to the EQUAL function. 

Some functions in INTERLISP automatically assume that one or more of 
their arguments are not to be evaluated; that is, they ar assumed to be “‘quoted.” 
SETQ is one of these. It assumes that its first argument (for example, X) is to be 
assigned a value. A variant of SETQ which assumes that both its arguments are 
quoted is SETQQ. Compare the following examples: 
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—(SETQ x1 'apples) 
apples 


<(SETQQ x2 apples) 
apples 


=I 
apples 


x2 
apples 


The INTERLISP function that prevents the evaluation of its argument is 
QUOTE. It takes the form 


Function: QUOTE 
KWOTE 
# Arguments: 1 
Argument: 1) an S-expression, EXPRESSION 
Value: The literal value of its argument. 


QUOTE is an NLAMBDA, nospread function. QUOTE returns the 
PRIN1-PNAME of that argument. However, because we use the quoting facility 
so much in INTERLISP, a convenient shorthand notation is provided for enter- 
ing the QUOTE function. We prefix the S-expression to be quoted by a single 
apostrophe (sometimes called a guote-mark). The single apostrophe is treated as 
a read macro (see Section 14.5). 

Internally, INTERLISP requires all data to be expressed in a strict S-ex- 
pression form. The quote-mark notation does not fit this form. So, the IN- 
TERLISP function that reads data typed in by the user converts all ’¢S-expres- 
sion) forms to (QUOTE <S-expression)) forms. Thus, while we type in 


(CAR 'x) 
what INTERLISP really sees is 
(CAR (QUOTE x)) 


When we attempt to give QUOTE more than one argument, it generates a 
PARENTHESES ERROR. For example, 


«(QUOTE i (CONS see her)) 
PARENTHESES ERROR 


because QUOTE does not know how to process the second argument. 


56 Primitive Functions 


An alternate function, KWOTE, returns a value which is its argument as a 
literal value. KWOTE is a LAMBDA function; that is, it arguments are evalu- 
ated. For example, 


<(SETQ x 'apples) 
apples 
<(SETQ y 'oranges) 
oranges 


<(KWOTE (list x y)) 
(QUOTE (apples oranges) ) 


If the value of its argument is a number, which is a literal value, KWOTE 
merely returns that number: 


<-(SETQ pi 3.141592) 
3.141592 


«+ (KWOTE pi) 
3.141592 





Similarly, if the value of the argument is NIL, KWOTE merely returns NIL: 


<—(SETQ truth-flag NIL) 
NIL 


«(KWOTE truth-flag) 
NIL 


3.5 CONDITIONAL EXECUTION: COND 


INTERLISP provides a conditional execution facility through the function 
COND. The format of the COND expression is 


Function: COND 
# Arguments: 1-N 


Arguments: any S-expressions 

Value: The value of the last statement in the 
first S-expression whose CAR evaluates to 
T . 


COND is an NLAMBDA, nospread function. A COND expression takes the 
following format (when prettyprinted): 
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(COND 
(<test1) ... <resulti)) 
(<test2) ... (result2)) 


a 


({testN) a (resultN) )) 


3.5.1 Executing a COND Expression 


The elements of a COND statement are called clauses. Each clause is composed 
of a test phrase, represented as an S-expression, followed by zero or more action 
phrases, represented as S-expressions, which are actions to be taken if the test 
evaluates true. 

CONDs are executed as follows: 


Execute the test of the first clause. If it is true (i.e., T), then execute all of 
the S-expressions comprising the result. The value of the COND is the value 
of the last S-expression in the result that is executed. 

If the test returns NIL when evaluated, proceed to the next clause. 
Continue to evaluate the tests of each clause in turn until one returns a non- 
NIL value. If this occurs, execute the S-expressions in the result as 
mentioned above. 

If no clause evaluates successfully, the value of the COND is NIL. 


Suppose we wanted to determine the type of an argument presented to a 
function. We could use COND to execute a sequence of tests that could serve to 
identify the argument’s type. A possible definition for a function that captures 
this idea is 


(DEFINEQ 
(test-argument (an-argument) 
(COND 

((LISTP an-argument) 'LIST) 
((NUMBERP an-argument) 'NUMBER) 
((STRINGP an-argument) 'STRING) 
((ATOM an-argument) 'ATOM) 
(T 'UNKNOWN) ) 

)) 


In this example, there are five clauses. The first clause consists of the test 


(LISTP an-argument) 
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and the result 
'LIST 


If the argument passed to TEST-ARGUMENT were a list such as (A B), 
then TEST-ARGUMENT would return the value LIST. LISTP is a predicate 
(see Chapter 4) which returns either a true (T) or false (NIL) value. 


3.5.2 The Default Clause 


The last clause (T NIL) in the example above is often called a default clause 
because it will be executed if no other clause succeeds. The test in the default 
clause always evaluates to true because it is the single atom T. Thus, the result 
will always be executed. For example, 


<(SETQ x (ARRAY 10 5 5)) 
[ARRAYP]#1, 1044 


«(test-argument x) 
unknown 


because X is not one of the data types tested for in TEST-ARGUMENT. Thus, 
none of the first four clauses succeeds. The default clause is executed and re- 
turns UNKNOWN. 

Because a clause with T as its test is always evaluated, it should always be 
the last clause in the COND expression. Clauses appearing after the T clause in a 
COND expression will never be executed because they can never be reached dur- 
ing normal program flow. This is a frequent error made by novice LISP pro- 
grammers that is easy to avoid. 


3.5.3 Test Phrase Values 


The test of a clause must return a true or false value to determine whether the 
result is executed or not. Many functions do not return T but some value (for 
example, MEMBER). If we required the value of the test to be only T or NIL, 
then any function returning other than T would have to be tested for a non-NIL 
value to produce a T. Consider the following COND fragment: 


(COND 
((MEMBER item bag) item) 


MEMBER always returns the fragment of a list beginning with its first argu- 
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ment if that first argument is indeed a member of the list (see Section 4.8). Thus, 
to ensure a T or NIL value, we would have to test what MEMBER returns via 


«-(NULL (MEMBER item bag) ) 
T or NIL 


Happily, INTERLISP does not require this constraint. Any value returned 
by a function used in the test phrase of a clause that is non-NIL suffices to indi- 
cate a successful execution. Thus, if (MEMBER item bag) returns a non-NIL 
value, the corresponding result phrases will be executed. 

Suppose we have a program which reads user queries and executes them 
against a database. In addition, the program may also respond to several com- 
mands that cause other functions to be called to perform administrative duties 
associated with program execution. We might write the function to read the 
query and decide what to do as follows (making judicious use of the COND ex- 
pression): 


(DEFINEQ 
(get-query (query) 
(PROG (first-character) 
(COND 
((NOT (NULL query) ) 
(RETURN query ))) 
loop 
(PRIN1 ''Enter Query: '') 
(SETQ query (READ) ) 
(SETQ first-character 
(CAR (UNPACK query) ) ) 
(COND 
((EQUAL (CAR (CHCON first-character) ) 
(CAR (CHCON '#))) 
(SETQ query 
(PACK 
(CDR 
(unpack query) ) ) ) 
(execute-query query) ) 
((EQUAL (CAR (CHCON first-character) ) 
(CAR (CHCON '?))) 
(print-commands) ) 
((EQUAL 'DEBUG query) 
(SETQ *debug* (NOT *debug*) ) ) 
((EQUAL 'OPTIONS query) 
(set-options) ) 
((EQUAL 'RULES query) 
(show-rules) ) 
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((EQUAL 'QUIT query) 
(RESET) ) 
(T 
(RETURN query) ) ) 
(GO loop) ) 


)) 
3.6 MULTIPLE CASE SELECTION: SELECTQ 


The COND statement tests each clause until it finds one that returns a true 
value, executes its consequents, and exits. Often, you will want to perform some 
function based on an explicit value of a variable or function. In a COND state- 
ment, you would have to test for each and every instance, perhaps through using 
EQUAL. This can be both tedious as well as leading to omitting one or more 
important cases. INTERLISP provides the SELECTQ function to select a spe- 
cific statement from among multiple cases. 

A SELECTQ expression takes the form 


Function: SELECTQ 


# Arguments: 2-N 


Arguments: 1) a selection phrase, SELECTOR 
2) a case clause, CLAUSE[1] 
3-N) case clauses, CLAUSE[2] ... clause[N] 


Value: The value of the last S-expression 
executed within the selected case clause 
or the default clause. 


SELECTQ is an NLAMBDA, nospread function. The general structure of 
the SELECTQ statement is given by: 


(SELECTQ <selection-value) 
(case[1] {clause[1])) 
(case[2] {clause[2])) 


(case[N] (elause[N])) 
(<default-clause)) ) 
3.6.1 Executing a SELECTQ Expression 


The <selection-value), SELECTOR, may be an atom or an S-expression that 
evaluates to an atomic value. It is compared with the case clauses as follows: 


1. If case[i] is an atom, then if (EQ SELECTOR case[i]) is true, 
INTERLISP executes the S-expression comprising clause[i]. 
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2. If case[i] is a list, then SELECTOR is compared with each element of the 
list in turn. If it is EQ to one of the elements of the list, then the S- 
expressions in clause[i] are executed. 


3. If none of the case[i] are selected by either of the two methods, the ¢de- 
fault-clause) is executed. There must always be a default clause present 
in a SELECTQ expression. 


Note that none of the case[i] are evaluated. Moreover, the clause[i] may be 
compound expressions as denoted by a PROGN (see Section 3.7.2). 

The value of a SELECTQ statement is always the value of the last S-expres- 
sion executed in any of the clauses or the <default-clause). 


3.6.2 SELECTQ Examples 


Suppose we can select one of several operations from a menu. How might we use 
SELECTQ to “‘switch’”’ to the proper execution stream for the selected opera- 
tion? Let us assume that the operations are CREATE, DELETE, UPDATE, 
DISPLAY, and EXIT. We might define a function as follows: 


(DEFINEQ 
(execute.operation (item menu key) 
(COND 
((EQUAL key 'MIDDLE) 
(SELECTQ (CAR item) 
(create 
(create.node) ) 
(update 
(update .node) ) 
(delete 
(delete.node) ) 
(display 
(display.node) ) 
(exit 
(exit.operations) ) 
(PROGN NIL)))) 


)) 


This example is drawn from a program in INTERLISP-D that makes use of 
the menu display and selection capability in the window system. You select an 
item from the menu by pressing the mouse key. Associated with the menu is a 
function to be executed when a selection is made. The function above ‘“‘switches”’ 
you to the appropriate function to be executed based on your selection. Note that 
the last expression in the SELECTQ statement is a PROGN which means do 
nothing if no selection was made. 
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The IRM [irm83] presents another simple example to select the number of 
days in a month. It looks like this: 


(SELECTQ month 
(february 
(COND 
((leapyearp) 
29) 
(T 28))) 
((april june september november) 30) 
(PROGN 31)) 


where LEAPYEARP tests if the current year is a leap year (e.g., divisible by 4). 

SELECTQ may also be used to invoke different processing routines based 
on the current state of the computation. Consider the case where your program is 
reading free text from a file. Your program must perform different kinds of pro- 
cessing based on the syntactic element it is trying to complete. Here is a fragment 
of a routine showing how SELECTQ might be used: 





(SELECTQ state 


(scanning 
(COND 
((test-character (LIST *PARAGRAPH* 
*DELIMITER* 
*SENTENCE*) ) ) 
(T 
(SETQ word (TCONC NIL char)) 
(SETQ state 'word)))) 
(word 
(COND 


((test-character *DELIMITER*) 
(PACK word) ) 


(T 
(TCONC word char) ))) 
(sentence 
(COND 
((test-character *NEW-LINE*) 
'*SENTENCE* ) 
(T 
(SETQ state 'scanning) ))) 
(paragraph 
(COND 
((test-character *NEW-LINE*) 
'*PARAGRAPH* ) 
(T 


(SETQ state 'scanning))))) 
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The basic idea is that STATE holds the current state of the scanning pro- 
cess. In this example, SELECTQ acts like a finite state automaton to switch the 


computation to the current processing routine based on the input it has just re- 
ceived. 


3.6.3 A Definition for SELECTQ 
We might define SELECTQ as follows: 


(DEFINEQ 
(selectq 
(NLAMBDA selectq-args 
(APPLY 'PROGN 
(SELECTQ1 
(EVAL (CAR selectq-args) ) 
13) (CDR selectq-args) ) ) 


Note that we must evaluate the SELECTOR to obtain its value for compari- 
son with the cases. 


SELECTQ1 is defined as 


(DEFINEQ 
(selectqi (selector clauses) 
(PROG (clause-list) 
(SETQ clause-list clauses) 
loop 
(SETQ clauses (CDR clauses) ) 
(COND 
((NULL clauses) 
(* 
A single case/clause pair 
in the SELECTQ, so return 
the sole clause. 


(RETURN clause-list) ) 
((OR 

(EQ 

(CAR (SETQ clause-list 
(CAR clause- 

list) )) 
selector) 

(AND 
(LISTP (CAR clause-list) ) 
(MEMBER selector 

(CAR clause- 

list)))) 
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(* 
The first of these 
expressions tests the 
selector against a single 
atom in a case. 
The second expression tests 
against a list of atoms in 
the case. 


) 
(RETURN (CDR clause-list) ))) 
(GO loop) ) 
)) 


Note that SELECTQ1 merely returns a list of the clauses to be executed 
when a match has been found for a particular case. The clauses are executed in 
the APPLY expression in SELECTQ through the application of PROGN. 


3.6.4 SELECTC: Selecting on Constants 


A variation on SELECTQ is the function SELECTC which performs selection on 
constants. It takes the form 


Function: SELECTC 
# Arguments: 2-N 


Arguments: 1) a selection phrase, SELECTOR 
2) a case clause, CLAUSE[1] 
3-N) optional case clauses, CLAUSE[2] ... 
CLAUSE[N] 


Value: The value of the last expression executed 
in the case clause that is selected. 


SELECTC is an NLAMBDA, nospread function. SELECTC allows you to 
determine the keys in the case phrase of a case clause at execution time. In SE- 
LECTQ, the key(s) in a case are literals that are not evaluated at execution time. 
However, the case[i] which determine the selection keys may be S-expressions 
which are evaluated to produce the possible selection keys. SELECTC is com- 
piled as a SELECTQ, so that its selection keys are treated as compile-time con- 
stants. 

The IRM [irm83] gives an example of how SELECTC may be used: 


(SELECTC number 
((for X from 1 to 9 
collect (TIMES X X)) 
"SQUARE"') 
(PROGN "'NON-SQUARE") ) 





3.7 Iterative Evaluation: PROG 65 


where the (for ... ) expression is evaluated at execution time to produce the list (1 
49 16 25 36 49 64 81) against which the selector (e.g., NUMBER) is compared. 


3.7 ITERATIVE EVALUATION: PROG 


The iteration mechanism provided by INTERLISP is the PROG statement. 
PROG allows you to write a “program” that may transfer control either forward 
(“‘skipping’’) or backward (“‘looping’’) over one or more statements. 

A PROG expression takes the format 


Function: PROG 
# Arguments: 1-N 
Arguments: 1) a list of variables, VARLST 


2-N) one or more S-expressions, 
EXPRESSION[1] ... EXPRESSION[N] 

Value: The value of the last S-expression 
executed within the scope of the PROG. 


PROG is an NLAMBDA, nospread function. The general structure of a 
PROG statement is 


(PROG {program-variable-list) 
(8-expressions) 
«label) 
(S-expressions) 


(GO (1abe1))) 


PROG operates as follows. The program variables specified in the <pro- 
gram-variable-list) are initialized to NIL or to a specified value (see below). The 
«S-expressions) are executed in sequence. Control of statement execution may 
be modified in two ways: 


1. A statement of the form (GO <label)) is executed that specifies the next 
statement to be executed is found after <label). Control may be transfer- 
red either forward or backward within the PROG body. 

2. A statement of the form (RETURN (¢S-expression)) is executed which 
causes the PROG to immediately exit with the value of the S-expression. 


Control may be transferred either forward or backward within the list of S- 
expressions depending on the position of the (label) that is the argument of GO. 
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Labels must always be literal atoms. They serve only as markers within the se- 
quence of S-expressions and are never executed. 

The value of a PROG statement is either the value of the RETURN state- 
ment or NIL if the PROG “‘falls off the end.’’ That is, the last S-expression in the 
sequence is executed without a RETURN statement being encountered. The lat- 
ter form is bad programming practice. 


3.7.1 Binding of PROG Variables 


A <program-variable-list) specifies the variables that are used by the PROG 
statement. They are similar to LAMBDA variables (see Chapter 8) in that they 
are bound locally to the PROG expression. Once the PROG expression is exe- 
cuted, the PROG variables cease to have a valid binding. If no program vari- 
ables are needed, you must specify NIL or () to indicate no local variables are 
needed. Otherwise, « program-variable-list) entries may take one of two forms: 


1. Anentry may be a literal atom which is then initialized to NIL. For exam- 
ple, 


(PROG (clause) ...) 


2. An entry may have the form ({atom) <S-expression)) where the atom is 
initialized to the value determined by evaluating the S-expression. For 
example, 


(PROG ((sum 0) (index 1)) ...) 


Attempting to use anything other than a literal atom as a PROG variable 
causes the error message ARG NOT LITATOM to be printed. You may not use 
NIL or T as PROG variable names, although they may be used to initialize 
PROG variables. Attempting to do so will cause the error message ATTEMPT 
TO BIND NIL OR T to be displayed and an error to occur. 

PROG variables exist only for the execution of the PROG. They have no 
value outside it. Thus, once you execute a RETURN statement, any PROG vari- 
ables within the PROG disappear (i.e., become undefined). 

PROG variables do not have to be unique. You may use the names of vari- 
ables that are external to the PROG as the names of PROG variables. However, 
atom names appearing in a ( program-variable-list) take precedence over those 
names external to the PROG. That is, the name indicates a new variable which 
named variable external to the PROG. 


Here is an example of a PROG expression used in a function that skips 
spaces while reading text from a file. 
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(DEFINEQ 
(skip-spaces (file-in) 
(PROG (char) 
loop 
(SETQ char (read-character file-in)) 
(COND 
((NULL char) 
(RETURN *EOF*) ) 
( (EQUAL 
(CAR (CHCON char) ) 
*EOF*) 
(RETURN *EOF*) ) 
((NOT (EQUAL 
(CAR (CHCON char) ) 
space) ) 
(RETURN char) ) 
. (T (GO loop) ))) 


Note that the RETURN expressions are embedded within the COND 
clauses. We could just as easily have written this function as follows: 


(DEFINEQ 
(skip-spaces (file-in) 
(PROG (char) 
loop 
(SETQ char (read-character file-in) ) 
(COND 
((NULL char) 
(GO end-of-file) ) 
( (EQUAL 
(CAR (CHCON char) ) 
*EOF* ) 
(GO end-of-file) ) 
((NOT (EQUAL 
(CAR (CHCON char) ) 
space) ) 
(GO exit) ) 
(T (GO loop) )) 
end-of-file 
(RETURN *XEOF*) 
exit 
(RETURN char) ) 
)) 


68 Primitive Functions 


This form makes the transfer of control more explicit in that the function 
skips forward to labels to exit the program. The style is akin to FORTRAN pro- 
gramming. 


3.7.2 Variations on PROG 


There are three variations to PROG. PROGI takes a sequence of S-expressions 
with no <program-variable-list), executes each in turn, but always returns the 
value of the first S-expression that it executed. PROG2 is similar to PROG1 but 
returns the value of its second argument. PROGN is a function which evaluates 
its arguments in order and returns the value of the last argument. All are 
NLAMBDA, nospread functions. They take the form 


Function: PROG1 
PROG2 
PROGN 
# Arguments: 1-N 
Arguments: 1-N) S-expressions 
Value: The value of the first (respectively, the 


second) S-expression in the argument list. 


Suppose we had a function that we knew was used to read the first atom of a 
command line. When it is called, it reads the atom, via RATOM, and also sets 
up the margin for echoing the command line. We want this function to return 
the atom read even though we test for the existence of a command and perform 
an additional function. *RATOM can do this using PROGI: 


(DEFINEQ 
( *ratom () 
(PROG1 
(SETQ command (RATOM) ) 
(AND 
(IS.COMMAND? command) 
(MAKEMARGIN) ) ) 
)) 


Note that I have defined *RATOM with a space between the ( and the func- 
tion name *RATOM so that it is distinguished from a comment. 

PROGN evaluates each of the S-expressions which are its arguments, but 
always returns the value of the last S-expression. 

PROG1, PROG2, and PROGN may be thought of as block delimiting state- 
ments. That is, they identify a sequence of statements that are executed as a 
single entity. Their only difference is which S-expression value they return. Pro- 
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grammers familiar with such block-structured languages as C and PASCAL will 
see a striking similarity to the BEGIN ... END blocks of those languages. 

PROG1 and PROGN are particularly useful in SELECTQ expressions. The 
cases of a SELECTQ expression take the form 


(<{selector) <action) ) 


The syntax of SELECTQ restricts (action) to a single S-expression. Using 
PROGN, we may collect any number of S-expressions into a single expression. 
For example, 


(<selector) 
(PROGN <action1) 
<action2) 
actions’) 


Note also that RETURN (see Section 3.7.4) takes a single S-expression as its 
argument. PROGN may be used here as well to execute a block of S-expressions 
the last of which becomes the value of the PROG. 


3.7.3 Transfer of Control 


PROG expressions allow you to develop iterative procedures in a function. Con- 
trol is transferred to another statement by executing GO. It takes the form 


Function: GO 

# Arguments: 1 

Arguments: 1) a label, LABEL 

Value: None, but control is transferred to LABEL, 


which must be a literal atom. 


LABEL identifies a location within the body of the PROG. If the label is 
undefined, GO generates an error with the message “UNDEFINED OR ILLE- 
GAL GO”. 

GO transfers control only within a function in which the PROG is defined. 
GO may transfer control either forward or backward within a PROG expression. 
PROG expressions may be nested within one another to any depth. When GO is 
executed, if the (label) does not appear within the current PROG, INTERLISP 
searches the hierarchy of PROGs looking for <label). Control is transferred to a 
statement higher in the hierarchy if it is identified by (label). For example, 
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(PROG Cried 


----) loop 


(PROG = (.«-) 


(PROG Cea) 


Be itd Mees Std At oe i { (GO loop)))) 


The GO expression transfers control to the label LOOP in the outermost 
PROG. 

Sometimes, PROGs may be independently situated within a function. Con- 
trol may not be transferred out of one PROG and into another because, once a 
PROG has been exited, no knowledge exists about its structure. For example, 





(DEFINEQ <function) 


(PROG = (.) 


(RETURN) ) 
(PROG ( soy 


SRS EL AP « (GO 1oop))) 


will generate an error because no knowledge of LOOP is retained once the first 
PROG has been exited. 

Control may be transferred either forward or backward within a PROG 
body. As in conventional programming languages, there are many possibilities 
for abusing the unconditional GOTO. 
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I recommend limited use of it according to the following rules: 


1. GO should transfer control only backward within a PROG body, except 
for rule 2; 

2. O may transfer control forward only to a label that identifies the last 
statement in the PROG body. For mnemonic purposes, this label should 
have the word EXIT as part of its name to indicate that the statements 
that follow will terminate the PROG. 


3.7.4 Exiting PROGs 
PROG expressions may be exited in two ways: 


1. Normally, by executing a RETURN expression. 
2. Abnormally, by “dropping off” the end of the PROG body. 


When a PROG expression terminates, it normally returns NIL as its value. 
RETURN allows us to stipulate a value that we want returned as the value of the 
PROG expression. 

RETURN takes the form 


Function: RETURN 

# Arguments: 1 

Argument: 1) an S-expression, EXPRESSION 

Value: The value of the S-expression, but a side 
effect is to terminate the PROG 
expression. 


EXPRESSION is an expression which is evaluated and becomes the value of 
the PROG. 

If RETURN is executed inside an interpreted function, but not within a 
PROG, it will force an exit from the last interpreted PROG expression that was 
entered, if any. Otherwise, an error will result. That is, you may call other func- 
tions within the body of a PROG expression and embed the RETURN from the 
PROG within one of those functions. However, this can lead to considerable 
confusion when reading program code and, I believe, constitutes poor program- 
ming practice. 

The compiler detects RETURN expressions that are not contained within 
PROG expressions in a function and generates an error at compile time. 


3.7.5 Implementing a DO-WHILE-UNTIL Construct 


Charniak et al. [char80] describe the implementation of a LOOP macro (using 
MACLISP features) that includes both DO-WHILE and DO-UNTIL capabili- 
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ties. INTERLISP does not provide macro features at the user programming 
level. Nevertheless, let us describe how the LOOP statement works as a guide for 
building PROG statements. 

The basic structure of the LOOP statement consists of a number of subordi- 
nate statements organized in sequence: 


(LOOP 
(INITIAL (initialization-expressions) ) 
(WHILE {while-condition) ) 
(DO {do-body) ) 
(NEXT {next-case-expressions) ) 
(UNTIL {until-condition) ) 
(RESULT <return-condition)) ) 


Most of these subordinate statements are optional. They may be combined 
in several ways to provide analogues to conventional DO-WHILE or DO-UNTIL 
iterations. Indeed, you may specify an INITIAL-DO-RESULT loop which acts 
exactly like a PROGN. 

Each of the subordinate statements is translated into a more familiar LISP 
statement by the macro. We will examine each of the statements and then show 
how they map into a general construct for an INTERLISP PROG statement. 


1. The INITIAL statement specifies the local variables of the PROG and 
assigns them values prior to the execution of any statements in the loop 
body. The format of an ¢initialization-expression) is a sequence of ¢vari- 
ables-expression) pairs. For example, 


(INITIAL SUM 0 COUNT 0) 


initializes two variables, SUM and COUNT, to 0. However, the expres- 
sion may be any valid S-expression. 

The INITIAL statement is translated into a sequence of SETQ state- 
ments plus a list of variables that become the ¢ program-variable-list) of 
the PROG statement. Thus, the example above becomes 


(PROG (SUM COUNT) 
(SETQ SUM 0) 
(SETQ COUNT 0) 


2. The WHILE statement tests a condition and terminates the loop if the 
condition yeilds a false (NIL) value. Stated in a different way, the loop 
body is executed as long as the ¢ while-condition) is true (T). The <while- 
condition) is just an S-expression that is to be evaluated. Thus, the 
WHILE statement translates as - 
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(OR 
(<while-condition) ) 
(GO EXIT$)) 


where EXITS is a label indicating the exit from the loop. Note that Char- 
niak’s macro generator inserts this automatically, but in our formulation 
you will have to code it explicitly. As an example, consider 


(WHILE (NEQ COUNT 10)) 


which translates to 


(OR 
(NEQ COUNT 10) 
(GO EXITS) ) 


The DO statement specifies the body of the loop. It contains one or more 
S-expressions that are to be executed on each pass through the loop. The 
expressions are evaluated from first to last in order. Transfers of control 
occurring within the DO-body must be explicitly encoded by the user. An 
example of a DO-body is 


(DO 
(SETQ NEXT-NUMBER (READ) ) 
(SETQ SUM (IPLUS SUM NEXT-NUMBER) ) ) 


which just reads a number and adds it to SUM. The translation of this 
DO-body is merely 


(SETQ NEXT-NUMBER (READ) ) 
(SETQ SUM (IPLUS SUM NEXT-NUMBER) ) 


. The NEXT statement specifies the local variables that are to be updated 


for the next loop iteration. The (next-case-expressions) take the form of 
<variable-expression) pairs where the variable is set to the value of the 
expression. Typically, the expression involves some previous value of the 
variable in its computation. An example of a NEXT statement might be 


(NEXT COUNT (ADD1 COUNT) ) 


which is translated to 


(SETQ COUNT (ADD1 COUNT) ) 


. The UNTIL statement terminates the execution of the loop when the 


{until-condition) evaluates to true (non-NIL). Stated differently, the 
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loop body is executed as long as the (until-condition) is false (NIL). The 
{until-condition) is just an S-expression that is evaluated. An example 
of an UNTIL statement might be 


(UNTIL (IGREATERP SUM 1000) ) 
which is translated to 
(AND 
(IGREATERP SUM 1000) 
(GO EXIT$) ) 
6. The RESULT statement specifies the value that the loop has when its 


termination conditions are satisfied. A (result-expression) is an S-ex- 
pression that is evaluated and becomes the loop value. For example, 





(RESULT (QUOTIENT SUM COUNT) ) 
which translates to 


(RETURN 
(QUOTIENT SUM COUNT) ) 


Let us put the pieces together, with appropriate comments to see the frame- 
work for a general model of a PROG statement using the concepts discussed by 
Charniak et al. Our final PROG statement would appear as 


(PROG (SUM COUNT) 
(* from INITIAL statement *) 
(SETQ SUM 0) 
(SETQ COUNT 0) 
LOOP$ 
(* from WHILE statement *) 
(OR 
(NEQ COUNT 10) 
(GO EXIT$)) 
(* from DO statement *) 
(SETQ NEXT-NUMBER (READ) ) 
(SETQ SUM (IPLUS SUM NEXT-NUMBER) ) 
(* from NEXT statement *) 
(SETQ COUNT (ADD1 COUNT) ) 
(* from UNTIL statement *) 
(AND 
(IGREATERP SUM 1000) 
(GO EXIT$) ) 
(GO LOOP$) 
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EXIT$ 
(* from RESULT statement *) 
(RETURN 
(QUOTIENT SUM COUNT) ) ) 


Note that Charniak’s macros would insert the loop markers LOOP$ and 
EXITS automatically, but you must explicitly encode them in your PROG con- 
struct. We see that this PROG construct merely reads ten numbers (or until their 
sum is greater than 1000), and computes the average. 


3.7.6 Other LISP forms 


PROG provides us with two key features for writing programs: 


1. The ability to perform iteration. 
2. The ability to define and initialize local variables. 


Other LISP dialects, such as MACLISP and FranzLisp, provide PROG ex- 
pressions. But they also provide alternative forms that accomplish the same 
functions but with (they claim) simpler forms. 

LET is an expression that allows you to declare and bind local variables. Its 
structure appears as 


(LET <local-variable-list) 
«forms-list)) 


where <local-variable-list) is a list of expressions of the form (<variable) 
<value)). <forms-list) is just a list of S-expression to be executed. The variables 
defined within a LET have existence only for the duration of the LET. You may 
think of a LET as a PROGN with local variable capability. 

DO is a special form that provides the local variable binding capability of 
the LET form with the iteration facility of PROG. DO has the following struc- 
ture: 


(DO ({local-variable-list)) 
(condition) <action-list)) 
(<expression[1]) 


(expression[N])) 

The <local-variable-list) has a form similar to that used in LET expressions: 
(<variable) <value) <update-expression) ) 

The <update-expression) is evaluated on each cycle of the DO loop to up- 


date the value of the variable. Variables with no (update-expression) are as- 
sumed to retain the initial value throughout the execution of the DO loop. 
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The (<condition) <action-list)) expression determines how the DO expres- 
sion terminates. On each pass through the DO loop, the <condition) is exe- 
cuted. If it evaluates true, then the expressions on the <action-list) are executed 
and the DO expression is exited. The value of the DO expression is the value of 
the last expression in the <action-list). 

The DO body is composed of expressions to be evaluated. Unlike PROG, 
however, when the DO reaches the last expression of the body, it begins a new 
cycle of the loop rather than falling off the end. The DO body may contain GO 
expressions and RETURN expressions to control the sequence of execution and 
when the loop is terminated, respectively. The DO body may be empty if all 
computation can be done by the (update-expression)s in the <local-variable- 
list). 

Charniak [char80], Winston [wins81], and Touretzky [tour84] discuss both 
the LET and DO forms in more detail. 

Do not confuse the DO discussed in this section with the DO operator pro- 
vided by CLISP. 


3.8 VALUE ASSIGNMENT: SET AND SETQ 


To assign values to variables, we use the SETQ function. SETQ takes two argu- 
ments: the variable to be set and an S-expression that may or may not be evalu- 
ated to provide a value for the variable. The format of SETQ (and SET as well) is 


Function: SETQ 
SET 
SETQQ 


# Arguments: 2 


Arguments: 1) a literal atom, ATM 
2) an S-expression, EXPRESSION 


Value: The new value of the variable. 


ATM must be a literal atom. Attempting to use anything other than a literal 
atom causes the error message “‘ARG NOT LITATOM” to be displayed. If 
ATM is NIL or T, the error message ‘ATTEMPT TO SET NIL OR T”’ will be 
displayed. 

SETQ and SET differ only in the evaluation of their first argument. SET 
evaluates its first argument to produce the name of the literal atom to be as- 
signed a value. SETQ does not. That is, SETQ assumes that the first argument 
is the name of the variable to which a value is to be assigned. 

Consider the following examples: 


+(SETQ computer-manufacturers (LIST 'univac 'ibm 'ncr)) 
(univac ibm ner) 
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— (SETQ an-industry 'computer-manufacturers) 
computer-manufacturers 


«(SET an-industry 
(APPEND computer-manufacturers 


(LIST 'honeywell) )) 
(univac ibm ner honeywell) 


“an-industry 
computer-manufacturers 


“—computer-manufacturers 
(univac ibm ner honeywell) 


Notice that SET evaluated the value of its first argument, which is COM- 
PUTER-MANUFACTURERS, and set it to the value of its second argument. 
Thus, when we display COMPUTER-MANUFACTURERS later, it has the new 
value that is shown. 

An alternative form of SETQ, SETQQ, assumes that both of its arguments 
are ‘‘quoted.”’ That is, neither argument is evaluated. Using the example above, 
we would have 


—(SETQQ computer-manufacturers (univac ibm ncr)) 
(univac ibm ner) 


3.9 SETTING AN ATOM’S VALUE CELL 


INTERLISP has been implemented in several different versions. One major dis- 
tinction concerns whether variables are deep or shallow bound on the stack. This 
notion will be discussed in more detail in Chapter 30. However, I will discuss 
several functions that set an atom’s value cell in this chapter because they are so 
widely used, most notably by the File Package (see Chapter 16). 


3.9.1 Binding Atoms from a File 


RPAQ and RPAQQ are NLAMBDA functions that set an atom’s value cell. 
They operate exactly like SETQ and SETQQ. They have the format 


Function: RPAQ 
RPAQQ 
RPAQ? 


# Arguments: 2 


Arguments: 1) a literal atom, ATM 
2) an S-expression, EXPRESSION 


Value: The value of the S-expression. 


The expression is evaluated for RPAQ and is not evaluated for RPAQQ. 
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<(RPAQ computer-manufacturers '(univac ibm ner)) 
(univac ibm ner) 


Both RPAQ and RPAQQ generate an error message “ARG NOT LITA- 
TOM” if ATM is not a literal atom. 

RPAQ? sets the top level value of ATM if and only if it does not have a 
current top-level binding, e.g., the contents of the value cell is the atom NO- 
BIND. It returns the value of EXPRESSION if the top level value is set, other- 
wise NIL. 

RPAQ, RPAQQ, and RPAQ? are intended to be used from within the File 
Package. 

These functions are often “hardwired”’ for efficiency because File Package 
operations are used so frequently by experienced INTERLISP programmers. 


3.9.2 Getting and Setting the Top Level Value 


As we mentioned in Section 2.1, atoms have value cells. When atoms are created 
by INTERLISP, they are allocated storage locations in memory. How a value is 
bound to an atom depends on the implementation: 


1. Deep binding systems save the variable’s new value on the stack. When a 
variable is referenced, its value is found by searching the stack for the 
most recent binding. If there is no binding on the stack, INTERLISP 
retrieves the value stored in the value cell of the atom. 

2. Shallow binding systems save the variable name and old value on the 
stack, and place the new value in the atom’s value cell. When a variable 
is accessed, the current value is always found in the value cell. 


INTERLISP provides two pairs of functions for accessing the value of a vari- 
able. They take the forms 


Function: GETTOPVAL 
GETATOMVAL 
# Arguments: 1 
Arguments: 1) an atom, ATM 
Value: The top level binding of ATM. 
Function SETTOPVAL 
SETATOMVAL 


# Arguments: 2 


Arguments: 1) an atom, ATM 
2) an S-expression, EXPRESSION 


Value: The value of the S-epxression. 
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GETTOPVAL returns the top level value of ATM, even if it is NOBIND, 
regardless of any other local bindings that may appear in the stack. 

GETATOMVAL always returns the value cell contents of ATM. In shallow 
bound systems, it is equivalent to executing (EVAL atm). In deep bound sys- 
tems, it defaults to GETTOPVAL. 

SETTOPVAL sets the top level value of ATM regardless of other local bind- 
ings that may appear on the stack. 

SETATOMVAL sets the value cell of ATM to the value of EXPRESSION. 
In a shallow bound system, it is equivalent to executing SET. In a deep bound 
system, it defaults to SETTOPVAL. 





Fundamental Predicates 


INTERLISP provides a large number of functions called predicates. A predicate 
is a function that tests some condition or attribute of its arguments. For exam- 
ple, a predicate may test whether its argument is an example of a given data 
type, whether it has a value satisfying certain criteria, or even whether it has a 
specific structure. The result of applying a predicate to its arguments is one of 
the atoms T or NIL (representing ‘‘true”’ or “‘false,’’ respectively) or some non- 
NIL value representing true. Some predicates are known as fundamental predi- 
cates because they test essential characteristics of LISP objects. This chapter will 
discuss several of the fundamental predicates common to most LISP implemen- 
tations. More predicates will be described in later chapters when we discuss the 
specific data types or subsystems with which they are associated. 

By convention, the name of a predicate should always be terminated by the 
character “‘P’’ to indicate that it is a predicate. For historical reasons, some of 
the fundamental predicates do not follow this rule. As an INTERLISP program- 
mer, it is good practice for you to terminate each application predicate function 
that you write with ‘“‘P”’ to indicate that it is a predicate. 


4.1 ATOM TESTING: ATOM AND LITATOM 


The simplest datatype available in INTERLISP is the atom. Atoms are indivisi- 
ble data structures. INTERLISP provides two predicates to test for the existence 
of atoms: ATOM and LITATOM. 


Function: ATOM 

# Arguments: 1 

Argument: 1) an S-expression, EXPRESSION 

Value: T if the argument is an atom; NIL 
otherwise. 


81 


82 Fundamental Predicates 


ATOM determines whether or not its argument is an atom. If it is, ATOM 
returns T; otherwise, it returns NIL. ATOM is the most general predicate for 
testing atoms whether they be numbers or literal atoms. ATOM returns NIL if 
its argument is an instance of one of the other fundamental datatypes such as 
strings, arrays, etc. In some dialects of LISP, ATOM is defined to be equivalent 
to NLISTP (see Section 4.5), e.g., an atom is assumed to be anything that is not 
a list. 

Another fundamental predicate is LITATOM. LITATOM tests whether or 
not its argument is a literal atom but not a number. 


Function: LITATOM 

# Arguments: 1 

Arguments: 1) an S-expression, EXPRESSION 

Value: T, if its argument is a literal atom; NIL 
otherwise. 


Suppose that we let the value of the atom GIRL-FRIENDS be the following: 





<(SETQ girl-friends 
'(jane nancy marcia susan ellen cheryl) ) 
(jane nancy marcia susan ellen cheryl) 


We can apply ATOM to this atom in the following ways: 
Test if GIRL-FRIENDS is an atom 


«(ATOM 'girl-friends) 
T 


Test the value of GIRL-FRIENDS 


«(ATOM girl-friends) 
NIL 


Note that INTERLISP distinguishes between the name of an atom and its 
value. In this case, GIRL-FRIENDS is an atom when we test its name, but when 
we test its value, we see that its value is not an atom but a list. 

We can apply ATOM to other arguments as follows: 

To a number 


<(ATOM 1378) 
T 
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although this is a redundant test because we know that numbers are literal at- 
oms. ; 


To a string 


(ATOM "Sandra is beautiful!) 
NIL 


because strings are not atoms, but a separate datatype. 
Let us also apply LITATOM to several examples: 


<(LITATOM 'girl-friends) 
T 


«(LITATOM 1378) 
NIL 


because numbers, while atoms, are not literal atoms. 


«(LITATOM "Sandra is beautiful") 
NIL 


4.1.1 An Alternative Atomic Predicate 


In other LISP dialects, the LITATOM predicate is replaced by the SYMBOLP 
predicate. SYMBOLP accomplishes the same function as LITATOM. 
Touretzky [tour84] notes that you may define SYMBOLP in terms of ATOM 
and NUMBERP (see below) as follow: 


(DEFINEQ 
(symbolp (x) 
(AND 
(ATOM x) 
(NOT (NUMBERP x))) 


)) 


where SYMBOLP will take the form 


Function: SYMBOLP 

# Arguments: 1 

Argument: 1) an S-expression, EXPRESSION 

Value: T, if its argument is a literal atom; NIL 


otherwise. 
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Let us apply SYMBOLP to a few examples to see how it works: 
«-(SYMBOLP 'girl-friends) 
T 
<-(SYMBOLP 1378) 
NIL 
4.2 NUMERIC PREDICATES 


INTERLISP provides several fundamental predicates for testing whether or not 
the value of an atom is a number. These include NUMBERP, ZEROP, FIXP, 
FLOATP, and SMALLP. 


4.2.1 Testing for Numbers 


NUMBERP returns its argument (meaning T) if the value of its argument is a 
number of any type; otherwise, it returns NIL. It takes the form 


Function: NUMBERP 

# Arguments: 1 

Argument: 1) an S-expression, EXPRESSION 
Value: T, if the value of its argument is a 


number; NIL otherwise 


Consider the following cases in which NUMBERP is used: 


<(SETQ a.number 1.7832) 
1.7832 


<(NUMBERP a.number) 
1.7832 (which means T) 


<-(SETQ another-number 100) 
100 


<(NUMBERP another-number) 
100 (which means T) 


Note that NUMBERP works on both integers and floating point numbers 
with equivalent results. 


<(NUMBERP ''1776") 
NIL 


*-(NUMBERP 'FIVE) 
NIL 
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NUMBERP works only with numeric representations of numbers. It does 
not know how to deal with string representations. We can circumvent this prob- 
lem by using 


+-(NUMBERP (MKATOM ''1776!'') ) 
1776 


4.2.2 Testing for Zero 


One of the most common tests that we make when performing arithmetic calcu- 
lations is to determine if the value of some variable or expression is zero. IN- 
TERLISP provides a fundamental predicate for testing if the value of an atom or 
S-expression is zero: ZEROP. ZEROP returns T if the value of its argument is 
zero; otherwise, it returns NIL. It takes the form 


Function: ZEROP 

# Arguments: 1 

Argument: 1) an S-expression, EXPRESSION 

Value: Hie if the value of its argument is zero; 


NIL otherwise 
Consider the following examples: 


<(SETQ a-number 0) 
0 


«-(ZEROP a-number) 
T 


Alternatively, we can test the value of an expression. For example, we can 
say 


«-(ZEROP (IPLUS 6 (IMINUS 6))) 
T 


where the value of the S-expression (IPLUS 6 (IMINUS 6)) is identically zero. 
ZEROP returns NIL if its argument is not a number. For example, 


«<-(ZEROP 'pi) 
NIL 


We should note that ZEROP is just a convenient function that could be de- 
fined in terms of other primitive functions. It is provided in most LISP systems 
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as a hardwired function for greater efficiency because it is so frequently used. A 
definition of ZEROP in terms of EQ would appear as 


(DEFINEQ 
(ZEROP (number) 
(COND 
((NUMBERP number) 
(EQ number 0)) 
(T NIL) ) 


)) 


Most arithmetic functions generate an error if their argument is nonnu- 
meric. Therefore, we test the argument to see if it is a number. If so, we compare 
it with 0 and return the result. Otherwise, we just return NIL. 

Note: ZEROP should not be used for testing if floating point numbers are 
equal to zero because it uses EQ which works only on integers. You should use 
EQP instead. For example, 





<(SETQ x 0) 

0 

-—(EQ x 0.0) 
NIL 

<—(EQP x 0.0) 

T 

<— (EQUAL x 0.0) 
T 


4.2.3 A Generalized Zero Predicate 


If you do not know whether your data will be integer or floating point numbers, 
you may want to define a generalized predicate for testing equality with zero. Let 
us call it EQZERO. It takes the following form 


Function: EQZERO 

# Arguments: 1 

Argument: 1) an S-expression, EXPRESSION 

Value: T, if its argument is zero either as a 


FIXP or a FLOATP; otherwise, NIL. 
We might define EQZERO as follows 


(DEFINEQ 
(eqzero (x) 
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(COND 
((NUMBERP x) 
(COND 
((FIXP x) 
(* 
It is an integer! 
) 
(ZEROP x)) 
((FLOATP x) 
(* 
It is floating point! 
) 
(EQP x 0.0)))) 
(T 
(* 
It is not a number, so return NIL 
) 
NIL) ) 


)) 


Consider the following examples: 


«-(SETQ anumber (IPLUS 6 (IMINUS 6)) 
0 


<(EQZERO anumber) 
T 


<(SETQ anumber (FPLUS 6.0 (FMINUS 6.0)) 
0.0 


<-(EQZERO anumber) 
T 


—(EQZERO 'pi) 
NIL 


4.2.4 Testing the Type of Number 


Numbers may be either integers or floating point numbers in INTERLISP. Two 
predicates allow you to test whether a number is an integer or a floating point 
number: FIXP or FLOATP. They take the following form 


Function: FIXP 
FLOATP 


# Arguments: 1 
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Argument: 1) an S-expression, EXPRESSION 


Value: The value of EXPRESSION if it is a number 
of the specified type; otherwise, NIL. 


Consider the following examples: 


«(SETQ anumber 100.765) 
100.'765 


«(FIXP anumber) 
NIL 


«(FLOATP anumber) 
100.765 


Both FIXP and FLOATP return NIL if their argument is not a number. 

INTERLISP provides a predicate for testing whether or not a number is a 
small integer. Small integers arose from early implementations of LISP where 
space was extremely limited. The value of a small integer could be represented in 
the value cell itself rather than being pointed to by the contents of the value cell. 
SMALLLP is the predicate that tests if a number is a small integer. It takes the 


form 
Function: SMALLP 
# Arguments: 1 
Argument: 1) an S-expression, EXPRESSION 
Value: The value of expression if it is a small 


integer; otherwise, NIL. 


The range of small integers is implementation dependent and is discussed 
further in Chapter 13. Consider the following examples (on INTERLISP-10): 


<(SMALLP 25) 

25 

<(SMALLP 33762) 
NIL 


because the range of small integers on INTERLISP-10 is -1535 to 1535. Other 
implementations will have different ranges. 


4.3 STRING TESTING: STRINGP 


INTERLISP provides a fundamental predicate for testing whether or not the 
value of its argument is a string. This predicate is called STRINGP. STRINGP 
takes the form 
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Function: STRINGP 

# Arguments: 1 

Argument: 1) an expression, EXPRESSION 

Value: T, if the expression has the datatype 


string; NIL otherwise. 


STRINGP returns the string if the value of its argument has a datatype of 
STRING; NIL otherwise. 


Consider the following examples: 


—(SETQ astring 
"The quick brown fox jumped over the lazy dog'') 
"The quick brown fox jumped over the lazy dog" 


<-(STRINGP astring) 
"The quick brown fox jumped over the lazy dog" 


«-(STRINGP 1.7875) 


NIL 

<-(STRINGP 'presidents) 
NIL 

<(STRINGP (MKSTRING 1776) ) 
"1776"! 


4.4 ARRAY TESTING: ARRAYP 


INTERLISP provides a fundamental predicate, ARRAYP, for testing whether 
or not its argument has a datatype of ARRAY. ARRAYP takes one argument— 
a potential array object. It determines whether or not the argument is an array 
object. If it is, it returns the value of the array object. If it is not, it returns NIL. 
ARRAYP takes the form 


Function: ARRAYP 
HARRAYP 
# Arguments: 1 
Argument: 1) An address of an array, ARRAYX 
Value: The value of the address if it is a 


pointer to an array object; 
otherwise, NIL. 


HARRAYP returns the address of a hash array if its argument has the data- 
type hash array. 
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Note: arrays may only be created by the function ARRAY (see Section 11.1). 
Arrays have a special format used by INTERLISP to manage their contents that 
requires allocation from a special storage pool. Arrays are discussed in more 
detail in Chapter 11. 


4.5 LIST TESTING: LISTP and TAILP 


INTERLISP provides a fundamental predicate to test whether or not its argu- 
ment is a list. This predicate is called LISTP. It takes the form 


Function: LISTP 
NLISTP 





# Arguments: 1 


Argument: 1) an S-expression, EXPRESSION 
Value: T, if value of argument is a list; NIL 
otherwise 


LISTP returns T if its argument is a list; otherwise, it returns NIL. Consider 
the following examples: 


<(SETQ presidents 
(CONS 'kennedy 
(CONS 'johnson 'nixon))) 
(kennedy johnson nixon) 


«-(LISTP presidents) 
T 


where the list is built by multiple CONSes. 


«-(SETQ presidents "kennedy johnson nixon"') 
''kennedy johnson nixon"! 


«-(LISTP presidents) 
NIL 


<(SETQ numbers 
(ARRAY 5 3 0)) 
[ARRAYP]#1, 2120 


«-(SETA numbers 1 100) 
100 


«(SETA numbers 2 200) . 
200 
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«(SETA numbers 3 300) 
300 


«-(LISTP numbers) 
NIL 


Neither arrays nor strings are represented as lists in INTERLISP. Thus, 
LISTP returns a value of NIL because they are not list-structures. For example, 


«-(LISTP NIL) 
NIL 


because NIL is considered to be a literal atom, rather than a list. Thus, while 
(LITATOM NIL) = (ATOM NIL) = T, LISTP applied to NIL returns NIL. 
You should exercise caution if the value of an object may be the empty list. 

Note that other implementations of LISP may consider NIL ("the empty 
list”) to represent a list whence LISTP will return T. This may cause difficulty 
when you attempty to transport source code from one dialect of LISP to another. 

An alternative form, NLISTP, returns the logical negation of LISTP, i.e., it 
asks if its argument is not a list. We might define NLISTP as 


(DEFINEQ 
(nlistp (x) 
(NULL (LISTP x) ) 
)) 


Consider the following example: 


«<-(NLISTP 'presidents) 
i i 


«-(NLISTP presidents) 
NIL 


where PRESIDENTS has the value (kennedy johnson nixon). 


4.5.1 Testing for the Tail of a List 


We have already seen how to take lists apart using the CAR and CDR functions. 
We often want to test whether or not the remainder of a list (that is, its tail) has a 
certain value. With CAR and CDR we can test the permissible combinations of 
these functions. However, most lists tend to be longer than four elements. Dis- 
membering such lists can be difficult if we have to write specific functions to take 
a given number of CDRs from a list. INTERLISP provides us with a convenient 
function to test the tail of a list for equivalence to a specific value, TAILP. 
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The generic format of this function is 


Function: TAILP 
# Arguments: 2 


Arguments: 1) a list structure, X 
2) any list structure, LST 


Value: X, if the value of X is EQ to some number 
of CDRs ()=0) of LST; NIL otherwise. 


TAILP returns the value of its first argument if that argument is a tail of its 
second argument; otherwise, it returns NIL. A tail is defined as the list resulting 
from taking some number of CDRs of the second argument. Consider the follow- 
ing examples: 


«-(SETQ girl-friends 
'(marcia mary janice angela elizabeth) ) 
(marcia mary janice angela elizabeth) 


«-(TAILP '(angela elizabeth) girl-friends) 
NIL 


because TAILP uses EQ to compare the two lists. In this case, ‘(angela eliza- 
beth) is a new list with a new storage allocation. On the other hand, 


«+(SETQ recent-girl-friends (CDDDR girl-friends) ) 
(angela elizabeth) 


«(TAILP recent-girl-friends girl-friends) 
(angela elizabeth) which means T 


because some number of CDRs of GIRL-FRIENDS returns a list that is EQ to 
the value of its first argument. 

The value of the first argument X must match exactly the structure of some 
tail of the second argument LST. Using EQ, the value is T if the value of X is a 
substructure of LST. That is, for TAILP to succeed, X must be embedded in 
LST such that the last N elements of LST correspond exactly to the elements of 
X. 

Thus, the following examples will not succeed: 


«-(SETQ acquaintance '(sandra) ) 
(sandra) 


«-(TAILP acquaintance girl-friends) 
NIL 
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because no number of CDRs produces a list that has the same value as a tail of 
GIRL-FRIENDS. 


+-(SETQ a-good-friend '(elizabeth) ) 
(elizabeth) 


*-(SETQ one-good-friend (CDDDDR girl-friends) ) 
(elizabeth) 


+-(TAILP a-good-friend girl-friends) 
NIL 


because A-GOOD-FRIEND does not point to the same structure in memory as 
the element ELIZABETH in the list GIRL-FRIENDS. 


«-(TAILP one-good-friend girl-friends) 
(elizabeth) 


because ONE-GOOD-FRIEND points to a list structure that is embedded 
within the second argument. 

For mathematical purposes, we say that X is a proper tail of LST if the num- 
ber of CDRs necessary to find the tail is greater than zero. Unfortunately, no 
indication of the number of CDRs required to determine the tail is provided by 
INTERLISP. 

We might define TAILP as follows 


(DEFINEQ 
(tailp (x lst) 
(AND x 
(PROG NIL 
loop 
(COND 
((NLISTP 1st) 
(RETURN NIL)) 
((EQ x lst) 
(RETURN x) )) 
(SETQ 1st (CDR 1st)) 
(GO loop) )) 
)) 


4.5.2 Counting the CDRs To Produce a Tail 


Suppose you wanted to know how many CDRs it will take to reach the tail of 
LST. We could modify the definition of TAILP to return this information in- 
stead of the value of the tail. Let us call this function TAILP? and let it take the 


form 
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Function: TAILP? 
# Arguments: 2 


Arguments: 1) an S-expression, X 
2) a list structure, LST 


Value: The number of CDRs required to reach the 
tail of LST if X satisfies TAILP on LST; 
otherwise, NIL. 


We might define TAILP? as follows 


(DEFINEQ 
(tailp? (x lst) 
(AND x 
(PROG (ntails) 
(SETQ ntails 0) 
loop 





(COND 
((NLISTP 1st) 
(RETURN NIL)) 
((EQ x lst) 
(RETURN ntails)) ) 
(SETQ lst (CDR lst)) 
(SETQ ntails (ADD1 ntails)) 
(GO loop) )) 
)) 


Note that TAILP? returns zero if X and LST are exactly equal; that is, no 
CDRs are required to produce the tail. If no number of CDRs would produce a 
tail because X is not a tail of LST, then TAILP? returns NIL. Otherwise, it 
counts the number of CDRs and returns that value. 


4.6 TESTING FOR EQUALITY 


In any programming language, we want to be able to test the equality of two 
objects. INTERLISP provides predicates for testing equality based on the data- 
type of the objects as well as the equality of certain attributes of the objects. 


4.6.1 EQ versus EQUAL 


The two basic predicates for testing equality are EQ and EQUAL. They have the 
following format 
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Function: EQ 
EQUAL 

# Arguments: 2 

Arguments: 1) a LISP object, X 
2) a LISP object, Y 

Value: T, if the objects are equal; NIL, 
otherwise. 


EQ and EQUAL differ in the way they compare their arguments. Consider 
two literal atoms that have the same name. Both EQ and EQUAL will return T. 
For example, 


—(EQ 'john 'john) 
ft 


(EQUAL 'john 'john) 
r 


both of which return T because each literal atom points to a unique location in 
storage. Thus, there is only one instance of JOHN in the entire INTERLISP 
memory. 

EQ and EQUAL produce the same result when their arguments have the 
same values if those values are literal atoms or numbers. For example, 


—(SETQ name-1 'john) 
john 

<(SETQ name-2 'john) 
john 

(EQ name-1 name-2) 
§ 


< (EQUAL name-1 name-2) 
4k 


because the values of NAME-1 and NAME-2 are the same literal atom. 

EQ operates by comparing the pointers of its arguments. If they point to the 
same structure, EQ returns T. Otherwise, it returns NIL. However, a problem 
arises when we apply EQ to more complex data structures such as lists and 
strings. Consider the following example 


«(SETQ languages-i-know 
(LIST 'paseal ‘fortran 'snobol 'cobol)) 
(pascal fortran snobol cobol) 
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<(SETQ languages-used 
(LIST 'paseal 'fortran 'snobol 'cobol)) 
(pascal fortran snobol cobol) 


<— (EQ languages-i-know languages-used) 
NIL 


«(EQUAL languages-i-know languages-used) 
T 


In this case, EQ returns NIL while EQUAL returns T. Why? We must re- 
member that each time LIST is applied to its arguments, it consumes additional 
storage to construct and return a new list. Thus, although the two lists LAN- 
GUAGES-I-KNOW and LANGUAGES-USED have the same elements, they 
are stored in different locations in memory. Because EQ uses pointers to data 
structures for comparison, the two lists are not equal because they have different 
addresses in memory. 

To test the equality of two data structures, we must use EQUAL, which 
compares the elements of the two structures. Thus, EQUAL returns T because it 
compares the successive elements of the two lists LANGUAGES-I-KNOW and 
LANGUAGES-USED, and finds them equivalent. 

EQUAL compares the top-level values of its arguments. Thus, two struc- 
tures will be EQUAL if 


1. EQ That is, pointers to the same structure. 

2. EQP That is, numbers with equal value. 

3. STREQUAL That is, strings containing the same sequence of charac- 
ters. 

4. Lists whose CARs are EQUAL and whose CDRs are EQUAL, applied 
recursively. 


EQ and EQUAL also work correctly when given pointers to the same array 
object. However, EQUAL returns NIL if it is asked to compare two different 
arrays because it does not perform an individual comparison of the array ele- 
ments. 

Why should you use EQ over EQUAL? Basically, it is a matter of efficiency. 
EQ is a primitive operation that may be encoded as a single instruction whereas 
EQUAL must always be defined as a subroutine because it has more work to do. 
On the other hand, if you are not too worried about the efficiency of your pro- 
gram, but are worried about it performing the proper checks every time, then I 
would encourage you to use EQUAL wherever possible. 

Programming Convention: It is a good idea, if you are a novice, to always 
use EQUAL to ensure that the proper evaluation of the two arguments is per- 
formed by INTERLISP. Because data structures that are EQUAL are not always 
EQ, many beginning programmers expend substantial effort in attempting to 
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determine why a program does not work correctly even though the data appear 
to be exactly the same. 

Note that some dialects of LISP allocate new storage every time a number is 
created even though that number may already be represented in memory. Thus, 
two numbers may never be guaranteed to be EQ, even if they are EQUAL. 


4.6.2 Atomic Equality 


When we have complex data structures, we may want to know if they are exactly 
equal throughout the entire structure. To determine total equality, we must de- 
scend to the atomic level throughout the data structure. EQUAL does not oper- 
ate in this manner since it compares only top-level values. To thoroughly test two 
data structures, INTERLISP provides the predicate EQUALALL. 

EQUALALL always descends to the atomic level of each of its arguments to 
determine equality. Thus, it should be used when comparing arrays, user data 
types, or complex structures having multiple levels of sublists beneath the top 
level. It takes the form 


Function: EQUALALL 

# Arguments: 2 

Arguments: 1) a data structure, X 
2) a data structure, Y 

Value: T, if each element of X is EQUAL to the 
corresponding element of Y; otherwise, 
NIL. 


EQUALALL may be used to determine the equality of two arrays by inspect- 
ing their contents. Let us define two arrays as follows 


<(SETQ Al (ARRAY 5 5)) 
[ARRAYP]#542224 


<(SETQ A2 (ARRAY 5 5)) 
[ARRAYP ]#542233 


Clearly, EQ and EQUAL will not work on the values of Al and A2, respec- 
tively, because they are different addresses for arrays. Let us initialize the arrays 
as follows (using a CLISP expression): 


«<-(FOR I FROM 1 TO 5 
DO 
(SETA A1 I (ITIMES I 100)) 
(SETA A2 I (ITIMES I 100))) 
NIL 
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«(FOR I FROM 1 TO 5 


DO 

(PRIN1 (ELT A1 I)) 

(TAB 20) 

(PRINT (ELT A2 I))) 
100 100 
200 200 
300 300 
400 400 
500 500 


Now, let us compare Al and A2 for equality using EQUALALL: 


<(EQUALALL A1 A2) 
T 


because EQUALALL descends into the array to compare individual elements. 
Now, let us compare two lists which have equivalent elements but are not 
EQ or EQUAL. First, let us define the lists 


<—(SETQ LST1 
(LIST 'red 
'yellow 
(LIST 'green 'blue) 
(LIST 'black) )) 
(red yellow (green blue) (black) ) 


<(SETQ LST2 
(LIST 'red 
'yellow 
(LIST 'green 'blue) 
(LIST 'black) )) 
(red yellow (green blue) (black) ) 


These two lists occupy different locations in memory because LIST con- 
sumes new CONS cells each time it is called. Thus, we may compare the two lists 
for equality 


<-(EQ lst1 lst2) 
NIL 


+-(EQUALALL 1st1 1st2) 
T 
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4.6.3 Numeric Equality 
EQ returns T if two numbers have the same structure in memory. For example, 
<(SETQ ten 10) 
10 
-(EQ 10 ten) 
> 


However, EQ cannot compare an integer with a floating point number even 
though they may have the same value. For example, 


<(SETQ ten 10) 
10 


<(SETQ ften (FLOAT ten) ) 
10.0 


<—(EQ ten ften) 
NIL 


INTERLISP provides EQP to test numerical equality between two numbers. 
However, EQP does not do conversion to a canonical representation. Thus, EQP 
will succeed when 


<—(EQP ten ften) 
T 


but will fail when 


«(EQP ten 10.3) 


NIL 
EQP takes the format 
Function: EQP 


# Arguments: 2 


Arguments: 1) a number, X 
2) a number, Y 


Value: T, if the two numbers are equal; 
otherwise, NIL. 


EQP may be used to compare X and Y as objects. It returns T if X and Y are 
EQ; NIL, otherwise. X and Y may be array pointers or stack pointers. 
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4.6.4 Testing Equality of Length 


In many applications, you will want to know if the length of a list is at least equal 
to a given number. INTERLISP provides the predicate EQLENGTH to test the 
size of a list. The format of EQLENGTH is 


Function: EQLENGTH 
# Arguments: 2 


Arguments: 1) an S-expression, EXPRESSION 
2) a minimum length, LEN 


Value: T, if the S-expression has the minimum 
length; NIL, otherwise 


A simple definition of EQLENGTH might appear as 


(DEFINEQ 
(eqlength (expression len) 
(IGEQ (LENGTH expression) len) 
)) 


Whatever the length of EXPRESSION, LENGTH must traverse the entire 
structure to determine its length before the comparison of values may take place. 
If EXPRESSION is very long, substantial time may be consumed in determining 
its length. Moreover, if EXPRESSION is a circular list, LENGTH never termi- 
nates until the operating system steps in. 

A more efficient version of EQLENGTH that is safe to use with circular lists 
can be defined as 


(DEFINEQ 
(eqlength (expression alength) 
(PROG (alst the-length) 
(SETQ alst expression) 
(SETQ the-length 0) 
LOOP 
(COND 
((CAR alst) 
(* 


If there is a CAR cell, 
increment the counter for 
the length of the list. 


) 
(SETQ the-length (ADD1 the- 
length) ) 
(SETQ alst (CDR alst)) 
(T 
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(RETURN NIL))) 
(COND 


((EQUAL the-length alength) 
(% 


Exit with T if and only if 
the list has a length equal 
to ALENGTH. 


) 
(RETURN T))) 
" (GO LOOP) ) 


In this definition, EQLENGTH will terminate when ALST is determined to 
have the minimum length specified or ALST is determined to have a length less 
than that specified. It works for circular lists because the number of compari- 
sons is bounded by ALENGTH. 


4.6.5 Testing Complex or Circular Structures 


Some applications may require the use of circular structures (although this is not 
generally recommended). Other applications require complex structures where 
we want to know only if they are equal to some depth of recursion. INTERLISP 
provides the predicate EQUALN to test if two structures are equal to a given 
depth. Its format is 


Function: EQUALN 


# Arguments: 3 


Arguments: 1) an S-expression, EXP1 
2) an S-expression, EXP2 
3) a depth, DEPTH 


Value: T, if EXP1 equals EXP2 to the given depth 
and no further recursion is possible; 
?, if EXP1 equals EXP2 and further 
recursion is possible; NIL, otherwise. 


EQUALN uses DEPTH to determine how deep to search in the complex 
structure. For example, 


<—(EQUALN '(((a)) b) '(((2)) b) 2) 


because at level 2 of the CAR recursion, it still has to compare (A) to (Z). At level 
2 they are equal, but further recursion remains, so equality is undetermined. 
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<—(EQUALN '(((a)) b) '(((2)) b) 3) 
NIL 


With the depth were set to 3, EQUALN would return NIL because it would 
compare A to Z and find them not equal. 


(EQUALN '(((a)) b) '(((a)) b) 3) 
T 


Note that DEPTH may be set to 0. Consider the following simple test cases: 


“(EQUALN '(A) '(A) 0) 
? 


«-(EQUALN '(A) '(A) 1) 
si 


4.6.6 Testing for Non-Equality 


Just as we may test for equality, we may also test for non-equality. INTERLISP 
provides the predicate NEQ to determine if two data structures are not equal to 
each other. This test is very simple because INTERLISP uses EQ to compare the 
pointers to the two structures. NEQ returns T if the two structures are not equal; 
otherwise, it returns NIL. It takes the form 


Function: NEQ 
NOTEQUAL 
# Arguments: 2 
Arguments: 1) an S-expression, EXPRESSION1 
2) an S-expression, EXPRESSION2 
Value: T, if EXPRESSION1 is not equal to 


EXPRESSION2; NIL, otherwise. 
A simple definition of NEQ might appear as 


(DEFINEQ 
(neq (expressionl expression2) 
(NOT (EQ expressioni expression2) ) 
)) 


Note that because NEQ uses EQ to compare the two data structures, the two 
data structures may be EQUAL without being EQ. Thus, you may also want to 
define a function NOTEQUAL which ensures that they are not equal at the top 
level. 
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A simple definition of NOTEQUAL might appear as 


(DEFINEQ 
(notequal (x y) 
(NOT (EQUAL x y)) 
)) 


Note that you may also want to define a function NOTEQUALALL which 
determines that two structures are not equal at the atomic level. 


4.6.7 Testing for Null 


INTERLISP provides the predicate NULL to test whether or not its argument 
has the value NIL. NULL returns T if the argument has the value NIL. Other- 
wise, it returns NIL. Its format is 


Function: NULL 

# Arguments: 1 

Argument: 1) an S-expression, EXPRESSION 

Value: T, if the value of EXPRESSION is NIL; NIL, 
otherwise. 


Consider the following examples: 


«(NULL (LIST) ) 
T 


because NIL is treated as a literal atom. 


«-(NULL (CONS) ) 
NIL 


4.7 TESTING VARIABLE BINDINGS 


Some functions use ‘‘free’’ or ‘‘global’’ variables in their computations. To pre- 
vent errors, you may want to determine whether or not a variable has been bound 
to a value before proceeding with the computation. INTERLISP provides the 
predicate BOUNDP to test if a variable is bound to anything in the current con- 
text. It takes the form 


Function: BOUNDP 
# Arguments: 1 


<= 
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Argument: 1) a variable, VAR 
Value: T, if the variable is bound in some 
environment. 


BOUNDFP returns T if its argument has a top level value. If the value of the 
variable is NOBIND or if the variable has not been created, BOUNDP will re- 
turn NIL. Consider the following example 


(PROG (var-1 var-2 var-3 ...) 
(SETQ var-1 <some value)) 
(SETQ var-2 NIL) 


(<a-function) var-1 var-2) 
(RETURN) ) 


Note that in the PROG we have bound VAR-1 and VAR-2 to some values. 
However, we have not bound VAR-3. If we were to use VAR-3 in A-FUNC- 
TION, an error would result (specifically, U.B.A.) because VAR-3 has not been 
given a value. The error results when INTERLISP attempts to (EVAL var-3) to 
determine its value. 

We can avoid this error by using BOUNDP to determine if a variable is 
bound before it is used. Thus, in A-FUNCTION, we might encode a condition as 
follows 


(COND 
((NOT (BOUNDP var-3) ) 
(SETQ var-3 NIL))) 


which sets VAR-3 to NIL if it does not have a value. 
Consider the following example (assuming we have never set X to any value) 


«+ (BOUNDP 'X) 

NIL 

<(SETTOPVAL 'X 'ABC) 
ABC 


<(BOUNDP 'X) 
T 
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4.8 DETERMINING MEMBERSHIP IN A LIST 


In many applications, a list represents a collection of related items. Often, we 
want to know whether or not another item is a member of that set of items. 
MEMBER determines if an item X is a member of a list. It takes the form 


Function: MEMBER 
MEMB 
EQMEMB 
# Arguments: 2 
Arguments: 1) an element, X 
2) a list of elements, LST 
Value: The tail of LST beginning with X if X is a 


member of LST; NIL, otherwise. 


MEMBER uses EQUAL to compare X against the elements of LST. Con- 
sider the following example, 


<(SETQ presidents '(reagan carter ford nixon johnson 


aerey 


(reagan carter ford nixon johnson ...) 


assuming that the list PRESIDENTS contains the last names of all the presi- 
dents of the United States. 


«(MEMBER 'disney presidents) 
NIL 


«(MEMBER ‘adams presidents) 
(adams monroe madison jefferson adams washington) 


Note that PRESIDENTS contains the name ADAMS twice, representing 
the sixth and second presidents respectively. However, because we have ordered 
the list beginning with the most recent president, the first occurrence of ADAMS 
will be detected in the list. 

We might define MEMBER as follows 


(DEFINEQ 
(member (x lst) 
(PROG NIL 
loop 
(COND 


((NLISTP 1st) 
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(* 
If LST is not a lst, then 


return NIL 
) 
(RETURN NIL) ) 
( (COND 


((LITATOM x) 
(* 
If X is a literal 
atom, use EQ for speed 


in comparing. 


) 
(EQ x (CAR 1st))) 


(T 
(* 
Otherwise, compare X 
with the top level 
components of the 
first element of LST. 
) 


(EQUAL x (CAR 1st)))) 
(RETURN 1st))) 
(SETQ lst (CDR lst)) 
(GO loop) ) 
)) 


An alternative form, MEMB, uses EQ instead of EQUAL to perform its 
comparisons. MEMB should only be used if you are certain that the elements of 
list may be uniquely compared. That is, the elements of the list should either be 
numbers, T or NIL, or literal atoms. 

For MAKEFILE (see Section 17.3.1), you may specify a list of options that 
determines how the code that is written to the file will be processed. MAKEFILE 
checks the options that you specify to determine if they are valid, and sets certain 
flags that are used later in the function. An abstract of the code used to.check 
flags is shown below 


(COND 
((MEMB 'NOCLISP OPTIONS) 
(RESETSAVE PRETTYTRANFLG T))) 
(COND 
((MEMB 'FAST OPTIONS) 
(RESETSAVE PRETTYTRANFLG NIL) )) 


(MEMB ''CLISPIFY OPTIONS) 
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(MEMB 'CLISP OPTIONS) ) 
(RESETSAVE CLISPIFYFLG T))) 


Because MEMBER uses EQUAL, it will determine if two objects are equal 
even if they do not have the same memory location. MEMB, however, uses EQ 
which checks for equality of location. I suggest that you use MEMBER (even 
though it takes more time) when you are inspecting a list for an element. 

Another form, EQMEMB, is T if either X is equal to LST or X is a member 
of LST. In the definition of MEMBER given above, if LST is not a list, then 
MEMBER returns NIL. EQMEMB allows us to specify either an atom or a list 
as its second argument. If the second argument is an atom, EQMEMB deter- 
mines if it is identical to the first argument; otherwise, it invokes MEMBER with 
the two arguments. We might define EQMEMB as follows: 


(DEFINEQ 
(eqmemb (x y) 
(COND 
((nlistp y) 
(EQ x y)) 
Cr 


(MEMBER x y))) 








Logical Connectives 
and Predicates 


INTERLISP provides a number of functions for performing logical functions on 
collections of S-expressions. These logical functions include the Boolean AND, 
OR, and NOT, and several Boolean predicates including SOME and EVERY. 
You should note that the arguments to each of these functions are evaluated 
prior to application of the logical function to the set of results produced by those 
evaluations. 


5.1 LOGICAL CONJUNCTION 


A conjunction is an expression whose value is true if and only if each of its com- 
ponents evaluates to a true value. 

The logical AND function accepts an indefinite number of S-expressions as 
its arguments; the number of arguments may be zero. It takes the form 


Function: AND 

# Arguments: O-N 

Arguments: 1-N) one or more S-expressions, 
EXPRESSION[1] ... EXPRESSION[n] 

Value: The value of the last argument, if all of 


its S-expressions evaluate to T or its 
equivalent; otherwise, NIL. 


AND is an NLAMBDA, nospread function. Each of the arguments to AND 
is evaluated in turn until one such argument is determined to have a NIL value. 
At that time, the AND terminates, returning NIL. If all of its arguments have 
non-null values, AND returns the value of the last argument. For example, 


«(AND '(I CAME) '(I SAW) '(I CONQUERED) ) 
(I CONQUERED) 
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Consider the following examples: 
No arguments 


(AND) 
T 





because no argument is detected as having a value of NIL. 
First argument is NIL 


«(AND NIL (anything) ) 
NIL 


always results in NIL because its first argument is NIL. 
Some argument is NIL 


«-(SETQ presidents '(kennedy johnson nixon ford) ) 
(kennedy johnson nixon ford) 


<— (AND 
(MEMBER 'nixon presidents) 
(MEMBER 'ford presidents) 
(MEMBER 'disney presidents) ) 
NIL 


When the arguments to AND are evaluated, we see that the first two S-ex- 
pressions succeed because NIXON and FORD are members of the list PRESI- 
DENTS. However, upon evaluating the third S-expression, a value of NIL is 
returned because DISNEY is not a member of PRESIDENTS. Thus, a value of 
NIL is returned as the value of the AND function. The order of the S-expressions 
makes no difference in this example (but will below), so we can rewrite the above 
example as 


+ (AND 
(MEMBER 'nixon presidents) 
(MEMBER 'disney presidents) 
(MEMBER 'ford presidents) ) 
NIL 


In this case, the last S-expression will not be evaluated because the second S- 
expression has a value of NIL which terminates the execution of the AND func- 
tion. 

No arguments are NIL 


+ (AND 
(MEMBER 'nixon presidents) 
(MEMBER 'ford presidents) 
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(MEMBER 'kennedy presidents) ) 
(kennedy johnson nixon ford) 


In this example, all three S-expressions have non-null values. Therefore, the 
AND function returns as its value the value of the last S-expression [because 
MEMBER returns a non-null value if it succeeds (see Section 4.8)]. 


5.1.1 An Application of AND 


The AND function may be used in many interesting ways. One interesting form 
has been to simulate the action of an UNTIL clause in a DO...UNTIL loop 
[char80]. 


The WHILE...DO... loop formalism is created using the PROG function 
(see Section 3.7). A skeletal form would appear as follows 


(PROG (<variables) ) (* INITIAL *) 
(SETQ (variable) <expression)) 


(SETQ <variable) <expression)) (* INITIAL *) 


LOOP 
(OR (* WHILE *) 
«expressions) 
(GO EXIT) ) 
«expressions) (* DO *) 
(SETQ <variable) (expression) ) (* NEXT *) 
(AND (* UNTIL *) 
«expressions) 
(GO EXIT)) 
(GO LOOP) 
EXIT 
(RETURN <expression)) ) (* RESULT *) 


A detailed analysis of this formalism was discussed during the examination 
of the PROG function (see Section 3.7.5). 

When the AND function is reached in this formalism, we have already exe- 
cuted all of the <expressions) that correspond to the DO-body of an iterative 
loop. At that time, the (expressions) within the AND function are evaluated. If 
any of these <expressions) have a value of NIL, we jump to execute the loop once 
more. When all (expressions) have non-null values, we exit from the loop. 


5.2 LOGICAL DISJUNCTION 


A disjunction is an expression whose value is true if and only if at least one of its 
components evaluates to a true value. 
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The logical OR function operates in a fashion similar to the logical AND 
function. It also takes an indefinite number of arguments each of which is evalu- 
ated in turn. It takes the form 


Function: OR 

# Arguments: 0-N 

Arguments: 1-N) one or more S-expressions, 
EXPRESSION[1] ... EXPRESSION[n] 

Value: The value of the first non-NIL argument, 


if any of its arguments evaluates to T or 
its equivalent; otherwise, NIL. 


OR is an NLAMBDA, nospread function. However, OR returns the value of 
the first S-expression whose value is non-null; otherwise, it returns NIL if all its 
arguments have a value of NIL. Consider the following examples: 


No arguments 


<— (OR) 
NIL 


because no argument has a non-null value. 
First Argument is non-null 


<-(OR T <anything)) 
A 


because the first argument is always non-null, it returns T. 
Some argument is non-null 


«(OR 
(MEMBER 'nixon presidents) 
(MEMBER 'disney presidents) ) 
(nixon ford) 


returns the list (NIXON FORD) because NIXON is a member of the list PRESI- 
DENTS and MEMBER always returns the tail of the list consisting of the match- 
ing element. 

No argument is non-null 


<—(OR 
(MEMBER 'disney presidents) 
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(MEMBER 'churchill presidents) ) 
NIL 


because none of the S-expressions has a non-null value. 


5.2.1 An Application of the OR Function 


Reviewing the sample structure given in Section 5.1.1, you will see that OR is 
used to select a terminating condition for the loop. In this case, OR implements 
the WHILE phrase of the loop by allowing the iteration to continue if any of its 
arguments is non-NIL. 

We often combine AND and OR in expressions to test different conditions. 
In Section 4.6.3, we used EQP to test the equality of two numbers. Suppose that 
we do not care whether the numbers are equal, but do care about the equality of 
their signs. The function EQSIGNP allows us to test this concept. It is defined as 


(DEFINEQ 
(eqsignp (x y) 
(OR 
(AND 
(ZEROP x) 
(ZEROP y)) 
(AND 
(LESSP x 0) 
(LESSP y 0)) 
(AND 
(GREATERP x 0) 
(GREATERP y 0))) 
)) 


The first argument to OR tests a simple case (it executes more quickly than 
either of the following relational comparisons). It also handles the case where X 
is 0 and Y is 0.0. The latter two arguments to OR handle the cases where both 
arguments to EQSIGNP are less than or greater than 0. 


5.3 LOGICAL NEGATION 


Logical negation has the effect of returning the opposite truth value of its argu- 
ment. INTERLISP provides two functions to perform logical negation: NOT 
and NEGATE. 


5.3.1 Computing the Logical Negation 


NOT returns the opposite value of its argument. That is, it turns T (or some non- 
NIL value) into NIL, and NIL into T. It takes the form 
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Function: NOT 

# Arguments: 1 

Argument: 1) an S-expression, EXPRESSION 

Value: The logical negation of the value of its 
argument. 


The value given to NOT may be any S-expression, including atoms and lists. 
For example, 


«(NOT (LIST 'michigan ‘illinois 'purdue)) 
NIL 


Many of the predicates in INTERLISP do not have the corresponding oppo- 
site forms. Two which do are NLISTP, which is the opposite of LISTP, and 
NEQ, which is the opposite of EQ. As we saw in Section 4.6.6, we may create the 
opposite predicate by defining a function that prepends NOT to an existing 
predicate. In general, you will find these forms easier to read and understand 
than writing an S-expression of the form 


(NOT (<predicate) <arguments) ) ) 


wherever you want to use the opposite predicate. There is a minimal cost to this 
approach, namely, defining a new function with the proper name and definition. 


5.3.2 Creating Negated S-expressions 
NOT merely computes the opposite truth value of the value of its argument. 
NEGATE, on the other hand, returns an S-expression that would compute the 
opposite value. It takes the form 

Function: NEGATE 

# Arguments: 1 

Arguments: 1) an S-expression, EXPRESSION 

Value: The S-expression evaluating to the logical 

negation of the value of its argument. 


NEGATE returns an S-expression which will evaluate to the negative of a 
value. For example, 


«(NEGATE 'x) 
(NOT x) 
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«(SETQ x T) 
T 


«(NEGATE x) 
NIL 


NEGATE is written to inspect the structure of its argument and perform 
some simple Boolean manipulations to generate the resulting form. Consider the 
following examples: 


«(NEGATE '(AND x y)) 
(OR (NOT x) (NOT y)) 


Suppose we assign the values T and NIL to X and Y respectively. Then we 
may see how NEGATE operates: 


«(SETQ x T) 
T 


«-(SETQ y NIL) 
NIL 


(AND x y) 
NIL 


«(NEGATE '(AND x y)) 
(OR (NOT x) (NOT y)) 


<—(OR (NOT x) (NOT y)) 
T 


The corresponding form using OR is 


“(NEGATE '(OR x y)) 
(AND (NOT x) (NOT y)) 


NEGATE recognizes the negative predicates that are defined within IN- 
TERLISP. For example, 


«(NEGATE '(EQ x y)) 

(NEQ x y) 

«(NEGATE '(OR X (NLISTP y))) 
(AND (NOT x) (LISTP y)) 


If NEGATE cannot resolve the form into a series of predicates it knowns 
about, it prepends NOT to the value of EXPRESSION and returns that as its 
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value. Thus, if we had defined NOTEQUAL as a function (see Section 4.6.6), 
NEGATE does not know about it. Thus, we have the following case: . 


«(NEGATE '(EQUAL x y)) 
(NOT (EQUAL x y)) 


NEGATE works with any number of logical operators composed in an S- 
expression, but only at the top level of the expression. Consider the following 
complex expression: 


«(NEGATE '(OR (NOT b) (AND a (NOT (OR b d))))) 
(AND b (OR (NOT a) (OR b d))) 


5.4 UNIVERSAL QUANTIFICATION 


In predicate logic, a formula P(x) may have the value T no matter what assign- 
ment is given to the variable X. To assert that every value of X chosen from some 
domain satisfies the predicate P, we place a universal quantification symbol 
naming the variable in front of the predicate. INTERLISP provides a function to 
test whether or not all members of a list satsify a given predicate. 

EVERY tests if the application of a given function to each element of a list 
results in a value of T; otherwise, it returns NIL. It takes the form 


Function: EVERY 
NOTEVERY 


# Arguments: 3 


Arguments: 1) any S-expression, EVERYX 
2) an evaluation function, EVERYFN1 
3) a selection function, EVERYFN2 


Value: T if (EVERYFN1 (CAR EVERYX)) is T for all 
elements of EVERYX selected by EVERYFN2; 
NIL otherwise. 


EVERY takes a list, denoted by EVERYX, and applies a function, 
EVERYEN1, to its CAR, e.g., (EVERYFN1 (CAR EVERYX)). If the result of 
this computation is NIL, then EVERY returns NIL without further evaluations. 
Otherwise, it applies a second function, EVERYFN2, to generate the new 
EVERYX. If EVERYFN2 is NIL, EVERY simply computes (CDR EVERYX). 
Consider the following examples: 


EVERYFN1 is NIL, EVERYFN2 is NIL 
This is a degenerate form that is equivalent to 
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(MAPCAR everyx 'AND) 


EVERYEFN1 is non-null, EVERYFN2 is NIL 


This is the equivalent of applying EVERYFN1 to each element of the list 
EVERYX. For example, if EVERYFN1 is ATOM, then 


«(EVERY (LIST 'x 'y 'z) (FUNCTION ATOM) ) 
T 


EVERYEFN1 is NIL, EVERYFN2 is non-null 

This form allows a user to select those elements of EVERYX that will be 
tested by EVERY. Because EVERYFN2 is used to generate each new version of 
EVERYX, only those elements of EVERY will be tested. 


5.4.1 A Definition for EVERY 
We might define EVERY as follows: 


(DEFINEQ 
(every (everyx everyfni everyfn2) 
(PROG NIL 
loop 
(COND 
((NLISTP everyx) 
(* 


If EVERYX is not a list, 
apply EVERY to a listified 
form of EVERYX. 
) 
(RETURN 
(EVERY (LIST everyx) 
everyfn1) )) 
( (NULL 
(APPLY* everyfni 
(CAR everyx) 
everyx) ) 
(* 
Test the CAR of EVERYX with 
the specified predicate. If 
the result is NIL, EVERY 
fails for this instance of 
EVERYX. 


) 
(RETURN NIL) )) 
(SETQ everyx 
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(COND 
(everyfn2 
(* 
There is a selector 
function! So generate 
'a new version of 
EVERYX. 
(APPLY* everyfn2 everyx) ) 
(T 
(* 
The default case. 
) 
(CDR everyx) ))) 
(GO loop) ) 


)) 


An alternative form, NOT-EVERY, returns the opposite of EVERY if some 
of the elements of EVERYX do not satisfy EVERYFN1. We might define NO- 
TEVERY as follows: 


(DEFINEQ 
(notevery (everyx everyfni everyfn2) 
(NULL (EVERY everyx everyfni everyfn2) ) 
)) 


5.4.2 Applications of EVERY 


EVERY has numerous applications in INTERLISP programs for testing the 
consistency of data structures and values of elements of data structures. Con- 
sider the following examples: 


Test if every member of a list is a number 


(DEFINEQ 
(numbers? (lst) 
(EVERY lst (FUNCTION NUMBERP) ) 
)) 


+-(SETQ 1st '(1 -34 2.65 0 0.0 -32.09 2314)) 
(1 -34 2.65 0 0.0 -32.09 2314) 


<(numbers? lst) 
yi 


Test if every member of a list is an atom 
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(DEFINEQ 
(atoms? (1st) 
(EVERY lst (FUNCTION ATOM) ) 
)) 


+-(SETQ lst '(harding grant coolidge) ) 
(harding grant coolidge) 


(atoms? 1st) 
rz 


Similar functions may be defined to test any characteristic of a single-level 
list by substituting the appropriate predicate into the EVERY expression and 
choosing a suitable name for the function. I believe it makes INTERLISP pro- 
grams more readable to define new predicate functions in this manner rather 
than to use EVERY expressions directly in the program code. 


5.5 EXISTENTIAL QUANTIFICATION 


In predicate logic, a formula P(x) may have the value T if any one of its argu- 
ments satisfies the predicate. To assert that some value of X chosen from a suit- 
able domain satisfies P, we place an existential quantification symbol in front of 
the formula. INTERLISP provides a function for testing whether or not one of a 
list of values satisfies a given predicate. 

SOME tests if the application of a given function to each element of a list 
results in a value of T for some members of that list. It takes the form 


Function: SOME 
NOTANY 


# Arguments: 3 


Arguments: 1) a list, SOMEX 
2) an evaluation function, SOMEFN1 
3) a selector function, SOMEFN2 


Value: The tail of SOMEX, if at least one element 
of SOMEX satisfies SOMEFN1; NIL otherwise. 


SOME applies SOMEFNI to the CAR of SOMEX. If that value is non-NIL, 
SOMEX is returned as the value of SOME. Otherwise, SOMEFN2 is applied to 
SOMEX. If SOMEFN2 is NIL, SOME uses (CDR SOMEX). That is, it applies 
SOMEEN| to each element of SOMEX in succession until one of those elements 
returns a non-NIL value. The value of SOME is the tail of SOMEX beginning 
with the element which satisfied SOMEFN1. 

Consider the following cases: 


SOMEEN1 is NIL, SOMEFN2 is NIL 


120 Logical Connectives and Predicates 

This is a degenerate case that is equivalent to 

(MAPCAR somex 'OR) 
SOMEEFN1 is non-null, SOMEFN2 is NIL 

This is the equivalent to applying SOMEFN1 to each element of SOMEX. 
For example, if SOMEFN1 is GREATERP, then 


«(SOME (LIST 23.0 -45.0 0.0) (FUNCTION GREATERP) ) 
(23.0 -45.0 0.0) 





5.5.1 A Definition for SOME 
We might define SOME as follows: 


(DEFINEQ 
(some (somex somefni somefn2) 
(PROG NIL 
loop 
(COND 
((NLISTP somex) 
x 


If SOMEX is not a list, 
apply SOME recursively to a 
listified form of SOMEX. No 
need to pass SOMEFN2 since 
we know there's only one 
element of the first 
argument. 


) 

(RETURN 
(SOME (LIST somex) 
somefn1) ) )) 

((APPLY* somefni 

(CAR somex) 
somex) 

(* 
If this form evaluates to a 
non-NIL value, we have 
found at least one element 
of SOMEX that satisfies the 
predicate. 


) 
(RETURN somex) ) ) 
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(SETQ somex 
(COND 
(somefn2 
(* 
There is a selector 
function! So generate 
the new version of 


SOMEX. 
) 
(APPLY* somefn2 somex) ) 
(T 
(* 
The default case. 
) 
(CDR somex) ) ) ) 
(GO loop) ) 


)) 


An alternative form, NOTANY, performs the opposite operation from 
SOME. That is, if SOME returns NIL, meaning no element satisfied SO- 
MEFN1, then NOTANY would return T. 

We might define NOTANY as 


(DEFINEQ 
(notany (somex somefn1 somefn2) 
(NULL (SOME somex somefni somefn2) ) 
)) 
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List Manipulation 


Symbolic expressions are also called lists. A list is just a sequence of objects, 
such as atoms or other lists, enclosed in a pair of parentheses. The essence of 
programming in INTERLISP is manipulating lists to store information. This 
chapter discusses the basic list manipulation functions. 


6.1 CREATING LISTS 


We have discussed the list creation functions in Section 3.2. However, to make 
this chapter complete, we will summarize these functions for you. 

CONS adds a new member to the list by prefixing it to the front of the list 
which is given as its second argument. It takes the form 


Function: CONS 
# Arguments: 2 
Arguments: 1) any atom or list, EXPRESSION 
2) any list, LST 
Value: A list whose CAR is the value of the first 


argument and whose CDR is the value of the 
second argument. 


Consider the following example: 


<—(CONS 'x '(y z2)) 
(x y 2) 


If the second argument is not a list but another atom, then CONS produces 
a form known as a dotted pair. This form takes its name from the fact that the 
pointers to the two atoms occupy the CAR and CDR portions of a CONS cell. 
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«(CONS 'x 'y) 
(x . y) 


LIST creates a new list from its argument which may be atoms or lists. Typi- 
cally, LIST is used to create a new list from a sequence of atoms. It takes the 
form 


Function: LIST 

# Arguments: 1-N 

Arguments: 1-N) S-expressions, EXPRESSION[1] ... 
EXPRESSION[N] 

Value: A list of the values of its arguments. 


Consider the following example: 


«(LIST 'apple 'cherry 'lime) 
(apple cherry lime) 


APPEND joins two lists together at their top level. What this means is, figu- 
ratively, that if we place the two lists side-by-side and erase the innermost pair of 
opposing parentheses, we will see the new list take shape. It takes the form 


Function: APPEND 

# Arguments: 1-N 

Arguments: 1-N) lists, LST[1] ... LST[N] 
Value: A list of the S-expressions of the 


individual lists. 


Consider the following example: 


<-(APPEND '(sherry port) '(riesling pinot-noir) ) 
(sherry port riesling pinot-noir) 


We can visualize this by placing the lists side-by-side as shown below and 
erasing the innermost pair of opposing parentheses. 


( sherry port ) ( riesling pinot-noir ) 
ae 
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Erase this pair of opposing parentheses to yield 


(sherry port riesling pinot-noir) 


6.2 CONCATENATING LISTS 


When you append two or more lists together, the result is always a new list. 
Frequent invocations of APPEND will rapidly consume the available memory 
forcing the system to spend more of its time in garbage collecting the remnants 
we have left lying around. Moreover, we often want to amend a list without 
changing its name (as we must do in using APPEND). INTERLISP provides us 
with several concatenation functions that change the CDR portion of the last cell 
of all but the last argument when linking the argument lists together. In effect, 
they “‘smash”’ the current value of each last cell’s CDR portion and replace it 
(just as RPLACD does) with a new value—the pointer to the first cell of the next 
argument list. However, in performing this operation we destroy the integrity of 
the second argument because it is merged into the first argument. 


6.2.1 NCONC: Normal Concatenation 


NCONC is the INTERLISP function that performs normal concatenation of two 
or more lists. Each of its arguments is a list. It modifies the CDR portion of the 
last cell of each list to point to the first cell of the succeeding argument list. 
Obviously, this cannot occur for the last argument list, and so it remains unmod- 
ified. It takes the form 

Function: NCONC 

# Arguments: 2...N 

Arguments: lists 


Value: a pointer to the first argument 


NCONC is a nospread function. Consider the following example: 


«(SETQ french-wines (LIST 'pinot-noir 'merlot) ) 
(pinot-noir merlot) 


«(SETQ german-wines (LIST 'riesling 'sylvaner) ) 
(riesling sylvaner) 


«(SETQ wines (APPEND french-wines german-wines) ) 
(pinot-noir merlot riesling sylvaner) 


<french-wines 
(pinot-noir merlot) 
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<—german-wines 
(riesling sylvaner) 


<-(SETQ wines french-wines) 
(pinot-noir merlot) 


«-(NCONC wines german-wines) 
(pinot-noir merlot riesling sylvaner) 


“wines 
(pinot-noir merlot riesling sylvaner) 


where we see that the list WINES has physically been altered by execution of 
NCONC. 

NCONC can take more than two lists as its arguments. In this case, all but 
the last list will be physically altered by execution of NCONC. NCONC always 
returns a pointer to the first cell of the first argument as its result. 

NCONC may be given NIL as the value of its first argument. Since NIL is 
treated as both an atom and a list, the following is a valid invocation of NCONC: 


<(SETQ good-wines NIL) 
NIL ; 


<-(NCONC good-wines (LIST 'pinot-noir 'merlot)) 
(pinot-noir merlot) 


However, NCONC operates somewhat differently when it encounters this 
situation. We must realize that NCONC deals with pointers to lists rather than 
the lists themselves. Thus, when it encounters NIL as the value of GOOD- 
WINES, it does not know that this NIL is the value of GOOD-WINES as op- 
posed to the intrinsic atom/list NIL. The result would be to modify the system 
atom/list NIL permanently, which would produce future catastrophic results. 
Thus, NCONC checks to see if its first argument is NIL and, if so, returns a 
pointer to the second argument. 


“good-wines 
NIL 


Thus, although the value of the NCONC expression is (pinot-noir merlot), 
GOOD-WINES has not been changed. NCONC has not changed NIL the 
“‘atom”’ into a list. 

Note that the first argument of NCONC cannot be an atom in any case since 
NCONC is not allowed to change a non-list to a list in order to concatenate it. 
However, the second argument may be an atom. A variation of NCONC, 
NCONC1, is used to concatenate an atom to the end of a list. It takes the form 
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Function: NCONC1 
# Arguments: 2 
Arguments: 1) a list, LST 
2) any S-expression, EXPRESSION 
Value: A list composed of LST concatenated with 


the value of EXPRESSION. 
We might define NCONC1 as 


(DEFINEQ 
(NCONC1 (alst an-atom) 
(NCONC alst (LIST an-atom) ) 
)) 


Basically, NCONC1 just applies the function LIST to its second argument 
before performing the concatenation. However, since this operation is frequently 
performed, NCONC1 is often hardwired to make it more efficient. For example, 


<-(NCONC1 french-wines 'cabernet-sauvignon) 
(pinot-noir merlot cabernet-sauvignon) 


The definition for NCONC in terms of more primitive functions might ap- 
pear as 


(DEFINEQ 
(NCONC (list-of-lists) 
(PROG (a-list tail) 
(SETQ a-list 
(OR 
(SOME list-of-lists (FUNCTION LISTP) ) 
(RETURN 
(CAR (LAST list-of-lists))))) 
(SETQ tail 
(LAST (CAR a-list))) 
(MAPC 
(CDR a-list) 
( FUNCTION 
(LAMBDA (item) 
(RPLACD tail item) 
(SETQ tail (LAST tail))))) 
(RETURN (CAR a-list))) 


)) 
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6.2.2 TCONC: One at a Time Concatenation 


When we use NCONC1, INTERLISP must find the end of the list in order to add 
the new element. Many times we are faced with the situation where we must add 
multiple elements to the end of the list, but one at a time. As the number of 
elements to be added grows, NCONC1 rapidly becomes inefficient because it 
finds the end of the list anew on each invocation. 

TCONC solves this problem by remembering where the end of the list is 
from invocation to invocation. Each time it is called, TCONC inspects a pointer 
it has created for the list that shows where the end of the list resides in memory. 
Thus, updating a list can proceed very rapidly when one element at a time is 
added to its end. It takes the form 





Function: TCONC 

# Arguments: 2 

Arguments: 1) a list having the pointer format, 
POINTER 
2) the element to be added, ELEMENT 

Value: An updated pointer for succeeding 
operations. 


TCONC can be initialized in two ways: 


~ 1. If POINTER is NIL, TCONC creates a POINTER for you. 
2. If POINTER has a value, TCONC changes the value of POINTER. 


Consider the following examples: 


<(SETQ wines (TCONC NIL 'merlot)) 
((merlot) merlot) 


where the CAR of the list returned is the list that you are building and the CDR 
is the pointer to the last element added to the list. Thus, you can always deter- 
mine where you are in building the list if its proper assembly depends on a spe- 
cific sequence of steps. 

When POINTER is (NIL), TCONC will change the value of POINTER. 
Consider the following example: 


«-(SETQ fruits (LIST NIL)) 
(NIL) 


«<(TCONC fruits 'cabernet-sauvignon) 
((cabernet-sauvignon) cabernet-sauvignon) 


«fruits 
((cabernet-sauvignon) cabernet-sauvignon) 
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We usually build a list incrementally when we are repeating a function or 
sequence of statements several times. One likely candidate is within a PROG. 
Many times, however, we merely want to repeat one function a fixed number of 
times where each iteration generates a single element to be added to the list. In 
this case, we are likely to use the RPTQ or RPT function. 

Consider the following example: 


+ (RPTQ 5 
(SETQ list-of-numbers 
(TCONC list-of-numbers rptn))) 
((5 4 3 2 1) 1) 


We recognize that this statement produces a list that appears a lot like the 
vector produced by the APL index-generation operator. Let us capture it as a 
function, but produce the list in the proper order. 


(DEFINEQ 
(index-generation (index) 
(PROG (index-list) 
(SETQ index-list (LIST NIL)) 
(SETQ index-list 
(DREVERSE 
(CAR 
(RPT index 
(TCONC index-list RPTN))))) 
(RETURN index-list) ) 
)) 


We can define TCONC in terms of the elementary functions as follows 


(DEFINEQ 
(TCONC (pointer element) 
(PROG (pointer-list) 
(RETURN 
(COND 
((NULL pointer) 
(* 


POINTER is NIL. Create one 
with the value of ELEMENT 
and return it. 

) 

(CONS 
(SETQ pointer-list 

(CONS element NIL)) 
pointer-list) ) 
((NLISTP pointer) 
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(* 
Generate an error if the 
pointer is not a list. 
) 
(ERROR "Bad Argument-TCONC:"' 
pointer) ) 
((NULL (CDR pointer) ) 
(* 


Handle the case of the 
first-time call, whence 
there is no end-of-list 
pointer. 
) 
(RPLACA pointer (CONS element NIL)) 
(RPLACD pointer (CAR pointer) )) 


(* 


(T 
Handle all other cases. 


(RPLACD pointer 
(CDR 
(RPLACD (CDR pointer) 
(RPLACD (CONS element) 
(CDR pointer) )) 
. )))))) 


6.2.3 LCONC: Concatenating Lists 


TCONC is used to add elements to the end of a list. Many times, we want to add 
lists to the end. Again, the problem is that we must always find the end of the list 
each time we invoke NCONC. LCONC (for List Concatenation) maintains a 
pointer just as TCONC does, but its second argument must always be a list. It 
takes the form 


Function: LCONC 

# Arguments: 2 

Arguments: 1) a list having pointer format, POINTER 
2) a list, LST 

Value: is pointer list updated with the value of 


Consider the following example: 





6.2 Concatenating Lists 131 


«(SETQ wines (LIST NIL)) 
(NIL) 


<-(LCONC wines (LIST 'merlot 'sylvaner) ) 
((merlot sylvaner) sylvaner) 


Note that the CDR portion contains the value of the last list element that is 
added to the list. This convention is the same as that used for TCONC. Thus, if 
we had to add both lists and elements to a list, we can call both TCONC and 
LCONC with the same pointer structure. Given the pointer structure WINES 
above, consider the following example: 


<-(TCONC wines 'chablis) 
(merlot sylvaner chablis) chablis) 


<-(LCONC wines 'chablis) 
bad argument—LCONC 


because the second argument must be a list. 
We can define LCONC in terms of elementary functions as follows 


(DEFINEQ 

(LCONC (pointer a-list) 
(PROG (pointer-list) 

(SETQ pointer-list (LAST a-list) ) 

(RETURN 

(COND 
((NULL a-list) 
% 


If NIL is to be added to the 
existing list, just return the 
pointer. 


pointer) 
((NLISTP a-list) 
(* 
If the argument to be added is 
not a list, generate an error. 


) 
(ERROR "Bad Argument-LCONC: " 
a-list) ) 
((NULL pointer) 
(* 
Tf POINTER is NIL, create a new 
pointer with A-LIST as the sole 
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element, and the last atom of A- 
LIST as the marker. 


(CONS a-list pointer-list) ) 
((NLISTP pointer) 
(* 
If POINTER is not a list, 
generate an error. 


(ERROR "Bad Argument-LCONC: "' 
pointer) ) 
((NULL (CAR pointer) ) 
(* 


Handle the case (NIL). 


(RPLACA 
(RPLACD pointer pointer-list) 
a-list) ) 
(T 
(* 


Handle all other cases. 


(RPLACD (CDR pointer) a-list) 


(RPLACD pointer pointer-list) ) ) 
)) 


6.2.4 ATTACH: Concatenating at the Front 


Each of NCONC, TCONC, and LCONC adds elements, whether atoms or lists, 
to the end of a list. It is often useful to be able to add elements to the front of a 
list. For example, in maintaining an agenda of tasks to be accomplished, you 
may want to place the highest priority task at the front of the list. 


ATTACH adds an element to the front of the list by doing an RPLACA and 
RPLACD. Its format is 


Function: ATTACH 
# Arguments: 2 
Arguments: 1) an element, X 
2) a list, LST 
Value: The modified list, LST’. 


Consider the following example: 


«-(SETQ baryons '(proton muon kaon) ) 
(proton muon kaon) 
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«(ATTACH 'omega-minus baryons) 
(omega-minus proton muon kaon) 


“(ATTACH 'sigma-minus NIL) 
(sigma-minus) 


which is the same as performing (CONS ‘sigma-minus NIL). 


«(ATTACH (LIST 'tau-minus) baryons) 
((tau-minus) omega-minus proton muon kaon) 


ATTACH performs destructive modification of the list. The resulting list 
remains EQ to LST. 

If the second argument is not a list, INTERLISP generates an error message 
ARG NOT LIST. 

We might define ATTACH as follows: 


(DEFINEQ 
(attach (x lst) 
(COND 
((LISTP lst) 
(RPLACA 
(RPLACD lst 
(CONS (CAR 1st) 
(CDR 1st))) 
x) ) 
((NULL 1st) 


(* 
The second argument must be a 
list. 


) 
(ERROR "ARG NOT LIST" x))) 
)) 


6.2.5 Variations on Concatenation 


The CONCatenation functions use an extra CONS cell to keep track of the 
pointers to the list elements. INTERLISP provides two functions that avoid the 
overhead of the extra CONS cell: DOCOLLECT and ENDCOLLECT. They 


take the form 


Function: DOCOLLECT 
ENDCOLLECT 


# Arguments: 2 
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Arguments: 1) an item, ITEM 
2) a list, LST 
Value: A list with the item inserted. 


Consider the following examples: 


«+(SETQ particles '(neutrino electron W-boson) ) 
(neutrino electron W-boson) 


«(DOCOLLECT 'neutron particles) 
(neutron electron W-boson) 





“particles 
(neutrino neutron electron W-boson) 


Caution must be exercised in using DOCOLLECT because you may cause 
the machine to enter into an infinite loop that may only be exited by rebooting. 
Consider the example 


«-(SETQ particles NIL) 
NIL 


«-(DOCOLLECT 'positron particles) 


At this point, the machine begins printing an endless list as follows: 


(positron positron positron positron positron positron 
positron positron positron ... ad infinitum 


<(SETQ particles (LIST 'neutrino 'electron 'W-boson) ) 
(neutrino electron W-boson) 


«-(ENDCOLLECT particles 'tau-minus) 
(electron W-boson) 


“particles 
(neutrino . tau-minus) 


«-(ENDCOLLECT particles (LIST 'J-particle 'omega-zero) ) 
(electron W-boson) 


“particles 
(neutrino J-particle omega-zero) 


<(ENDCOLLECT NIL 'electron) 
electron 


“(SETQ particles '(electron proton) ) 
(electron proton) 
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«-(ENDCOLLECT particles NIL) 
(proton) 


“particles 
(electron) 


As we see, DOCOLLECT adds an item at the beginning of the CDR of the 
list, whereas ENDCOLLECT replaces the CDR of the list. In general, DOCOL- 
LECT maintains the list that it is building as a circular list. When you are ready 
to add the last item, you should use ENDCOLLECT, which returns a non-circu- 
lar list. Thus, DOCOLLECT and ENDCOLLECT are meant to be complemen- 
tary functions. 


Implementing DOCOLLECT 
DOCOLLECT may be implemented in terms of RPLACD as follows: 


(DEFINEQ 
(docollect (an-item a-list) 
(COND 
((NLISTP a-list) 
(RPLACD (SETQ a-list (LIST item) ) 
a-list) ) 
(T 
(CDR (RPLACD a-list 
(CONS item a-list))))) 
)) 


Implementing ENDCOLLECT 
ENDCOLLECT may be implemented using RPLACD as follows: 


(DEFINEQ 
(endcollect (item a-list) 
(COND 
((NULL item) a-list) 
(T 
(PROG1 

(CDR item) 
(RPLACD item a-list)))) 


)) 


Using DOCOLLECT in MAPCAR 
The IRM [irm78] suggests that MAPCAR may be defined, using DOCOL- 
LECT and ENDCOLLECT, as follows: 


(DEFINEQ 
(mapear (a-list a-function) 
(PROG (value) 
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loop 
(COND 
((NLISTP a-list) 
(RETURN (ENDCOLLECT value) ))) 
(SETQ value 
(DOCOLLECT 
(APPLY* a-function (CAR a-list) ) 
value) ) 
(SETQ a-list (CDR a-list)) 
(GO loop) ) 


)) 


6.3 SUBLIST EXTRACTION 


In Chapter 2, we saw that one way to take a list apart was to use the functions 
CAR and CDR. These work, respectively, on the head and the tail of a list. In 
addition, INTERLISP provides several functions that can operate on interior 
components of a list. 


6.3.1 Extracting the Last Element 


LAST allows you to retrieve the last node in a list, e.g., the contents of the last 
list cell. LAST takes the form 


Function: LAST 

# Arguments: 1 

Arguments: 1) a list, LST 

Value: A list whose element is the last node in 


LST; otherwise, NIL. 
If its argument is not a list, LAST returns NIL: 


(LAST 'rhomboid) 
NIL 


Otherwise, it returns the contents of the last cell of LST as a list. There are 
two possible cases: 


1. The last cell was appended (NIL in the CDR part). For example, 


«(LAST '(parallel quadrilateral rhomboid) ) 
(rhomboid) 
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2. The last cell was CONSed to the list. For example, 


«-(LAST '(parallel triangle quadrilateral . rhomboid) ) 
(quadrilateral . rhomboid) 


LAST is useful when you must obtain the last entry of a list. If the list is 
longer than four elements, you cannot use one of the CAR ... CDR combinations 
to retrieve the element. Using LAST, you do not need to know the length of the 
list to retrieve the last element. 

We might define LAST as follows: 


(DEFINEQ 
(last (1st) 
(PROG (xprev) 
(SETQ xprev NIL) 
loop 
(COND 
((NLISTP 1st) 
(RETURN xprev) ) ) 
(SETQ xprev lst) 
(SETQ lst (CDR 1st)) 
(GO loop) ) 
)) 


Note that XPREV always holds the previous element of X. Thus, when we 
determine that X is no longer a list, the previous element must be a list. Hence, it 
is returned as the last element of X. On the first pass through the code, if X is not 
a list, then NIL will be returned. See [knut68] for a detailed discussion of list 
manipulation algorithms. 


6.3.2 Extracting the Tailing N Elements 


NLEFT allows you to extract the rightmost N elements of a list where N is greater 
than the number of elements in a specified tail of the list. Its format is 


Function: NLEFT 
# Arguments: 3 


Arguments: 1) a list, LST 
2) extension, N 
3) the tail, TAIL 


Value: A list with N more elements than the tail. 
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Consider the following examples: 
1. TAIL is NIL (the usual case): 


«(SETQ awards '(tony oscar emmy coty) ) 
(tony oscar emmy coty) 


«-(NLEFT awards 2) 
(emmy coty) 


2. TAIL is non-NIL: 


<(SETQ tail (CDDDR awards) ) 
(coty) 


<(NLEFT awards 1 tail) 
(emmy coty) 


where the length of the tail is 1, and we are asking for a list whose length 
is 1 greater than the length of the tail. 


<(NLEFT awards 4 tail) 
NIL 


because there is no list that may be extracted from the first argument 
which meets the specified criterion, namely having a length 4 elements 
greater than the tail. 


If LST is not a list and is equivalent to TAIL, NLEFT returns NIL, except in 
the case where N is zero: 


<-(NLEFT (LAST awards) 1 tail) 
NIL 


«-(NLEFT (LAST awards) O tail) 
(coty) 


You may use NLEFT to work backwards through a list by setting TAIL to 
(LAST Ist). Then, by calling NLEFT repreatedly with different values of N and 
using CAR to strip off the head of the resulting list, you access the list in reverse 
order. When the result is NIL, you know that you have reached the end of the 
list. 

We might define NLEFT as follows: 


(DEFINEQ 
(nleft (lst n tail) 
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(PROG (x) 
(SETQ x lst) 
loop 
(COND 
((ZEROP n) 
(* 


N equal to 0 is equivalent 
to LAST. 


) 
(GO loop1) ) 


(EQ x tail) 
(NLISTP x) ) 
(* 

Return NIL if: 

1 The first argument is 
not a list. 

Se It is equal to the 
thing that is looked 
for. 

) 
(RETURN NIL) )) 
(SETQ x (CDR x)) 
(SUB1VAR n) 
(GO loop) 
loop1 
(COND 
((OR 
(EQ x tail) 
(NLISTP x)) 
(* 
Return 0 if N is O. 


) 
(RETURN lst) )) 
(SETQ x (CDR x)) 
(SETQ lst (CDR 1st)) 
(GO loop1) ) 
)) 


Note that if N is zero and TAIL is NIL, then NLEFT is equivalent to LAST. 
If N is zero and TAIL is non-NIL, then NLEFT operates like MEMBER. 


6.3.3 Extracting the Last N Elements 
LASTN extracts the last N elements of a list. It takes the form 
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Function: LASTN 
# Arguments: 2 


Arguments: 1) a list, LST 
2) an index, N 


Value: An S-expression consisting of the initial 
and final segments of a list. 


Assume LST has length equal to L elements. LASTN “‘breaks’’ a list at the 
Nth element. It returns an S-expression equivalent to 


(CONS initial . final) 
where 


Initial The first through L-N-1 elements of the list 
Final The Nth through L elements of the list 


If LST does not contain N elements (i.e., L less than N), LASTN returns 
NIL. 


Consider the following examples: 


«(SETQ lst '(the lazy fox jumped over the brown dog)) 
(the lazy fox jumped over the brown dog) 


«(LASTN 1st 5) 
((the lazy fox) jumped over the brown dog) 


«(LASTN 1st 10) 
NIL 


«(LASTN 1st 8) 
(NIL the lazy fox jumped over the brown dog) 


LASTN provides a convenient mechanism for decomposing complex list 
structures. The CAR of its result always returns the initial segment while the 
CDR returns the final segment. Let us assume the following complex structure: 


(class conceptualization properties constituents) 


which might be the syntax node structure in a natural language parser. 

We know that the list has a fixed structure but that the type of individual 
elements (except for the first) may be atoms or lists. We can defined the follow- 
ing functions: 
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(DEFINEQ 
(syntax:class (node) 
(car node) )) 
(DEFINEQ 
(syntax:concept (node) 
(CADR (LASTN node 3)))) 
(DEFINEQ 
(syntax:properties (node) 
(CADR (LASTN node 2)))) 
(DEFINEQ 
(syntax:constituents (node) 
(CADR (LASTN node 1)))) 


Note that we can extract an individual element by taking the CADR of 
LASTN of the original list where the element is the Nth element from the tail of 
the list. 

Although I have demonstrated this approach for a list of four elements, you 
can see that it is easily applicable to a list of N elements provided N is fixed. 


A Definition for LASTN 
We might define LASTN as follows: 


(DEFINEQ 
(lastn (lst n) 
(PROG (xlst ylst) 
(SETQ xlst (NTH lst n)) 
(COND 
((NLISTP 1st) 
(* 
If LST is not a list. 


) 
(RETURN NIL) ) 
((NULL xlst) 
(* 
If N is greater than the 
length of LST. 


) 
(RETURN xl1st) )) 
loop 
(SETQ xlst (CDR xl1st)) 
(COND 
((NULL x1st) 
(RETURN 
(CONS ylst 1st)))) 
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(SETQ ylst 
(NCONC1 ylst (CAR 1st))) 
(SETQ 1st (CDR lst) ) 
(GO loop) ) 
)) 


6.3.4 Extracting From the Nth Element 


Given a list of K elements, how do you extract from the Nth element (where N is 
less than K)? If N is 1, 2, or 3, you can use some combination of CARs and CDRs 
to retrieve it. You may use LAST if N equals K. Otherwise a complex function 
might be required with substantial testing for the length and end of the list for 
different cases. INTERLISP provides NTH to extract the tail of a list beginning 
with the Nth element where the length of the list is unknown. It takes the form 





Function: NTH 
# Arguments: 2 
Arguments: 1) an S-expression, EXPRESSION 
2) an index, N 
Value: The tail of the list beginning with the 


Nth element. 
Let us consider several cases, using the list 
<(SETQ games 
(LIST 'poker 'gin-rummy 'hearts 'bridge 
'canasta) ) 
(poker gin-rummy hearts bridge canasta) 


1. If N is 0, the value is (CONS NIL EXPRESSION). 


«(NTH games 0) 
(NIL poker gin-rummy hearts bridge canasta) 


2. If N is 1, the value is EXPRESSION. 


«(NTH games 1) 
(poker gin-rummy hearts bridge canasta) 


3. If N is 2, the value is (CDR EXPRESSION). 


«(NTH games 2) 
(gin-rummy hearts bridge canasta) 
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4. If (LENGTH EXPRESSION) is less than N, the value is NIL. 


“(NTH games 7) 
NIL 


5. Otherwise, the tail of EXPRESSION beginning with the NTH element is 
returned. 


<(NTH games 3) 
(hearts bridge canasta) 


We might define NTH as follows: 


(DEFINEQ 
(nth (expression n) 
(COND 
((IGREATERP 1 N) 
(* 
If N is less than or equal to 
zero. 


(CONS NIL expression) ) ) 
(PROG NIL 


loop 
(COND 
((EQUAL n 1) 
(RETURN expression) ) 
((NLISTP expression) 
(RETURN NIL) )) 
(SETQ expression (CDR expression) ) 
(SETQ n (SUB1 n)) 
(GO loop) ) 
)) 


6.4 COPYING AND REVERSING LISTS 


INTERLISP duplicates pointers to lists rather than duplicating the lists them- 
selves in many functions. For example, 


<—(SETQ computers 
(LIST 'atari-1200 'apple-IIe 'TRS-80) ) 
(atari-1200 apple-IIe TRS-80) 


<(SETQ microcomputers computers) 
(atari-1200 apple-IIe TRS-80) 
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creates an additional pointer to the list which is the value of COMPUTERS. We 
can verify this by checking to see if MICROCOMPUTERS and COMPUTERS 
are EQ. 


<(EQ microcomputers computers) 
T 


However, if we subsequently modify COMPUTERS, then the value of MI- 
CROCOMPUTERS is modified as well. 


<-(SETQ computers (APPEND computers 'iAPX-286) ) 
(atari-1200 apple-IIe TRS-80 iAPX-286) 


“microcomputers 
(atari-1200 apple-IIe TRS-80 iAPX-286) 


However, if we wish to modify COMPUTERS without modifying MICRO- 
COMPUTERS, then we must make a copy of COMPUTERS. This section de- 
scribes functions for copying lists. 


6.4.1 Copying List Elements 


COPY makes a copy of the list which is its argument. It returns the new list as its 
value. COPY duplicates elements of its arguments down to the non-list level. 
However, if some of its elements are strings or arrays, the new list will contain 
these same strings or arrays (via pointers to them). It takes the form 


Function: COPY 
# Arguments: 1 
Argument: 1) an S-expression to be copied, 
EXPRESSION 
Value: A copy (with new storage assigned) of its 
argument. 


Consider the following examples: 


«(SETQ countries '(france spain denmark norway) ) 
(france spain denmark norway) 


<(SETQ same-countries (COPY countries) ) 
(france spain denmark norway) 


«(EQ countries same-countries) 
NIL 


«(EQUAL countries same-countries) 
T 
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demonstrates that while the lists are equivalent, they are not the same data struc- 
ture. 


<(SETQ some-sf-writers '("Asimov'"' "Dick"! 
"Saberhagen'') ) 
(""Asimov'" "Dick" "Saberhagen!') 


<(SETQ good-sf-writers (COPY some-sf-writers) ) 
("Asimov'"' "Dick" "Saberhagen'"') 


(EQ some-sf-writers good-sf-writers) 
NIL 


(EQUAL some-sf-writers good-sf-writers) 
+ 


<(SETQ seed 'tamarind) 
tamarind 


<(SETQ new-seed (COPY seed)) 
tamarind 


<-(EQ seed new-seed) 
Tr. 


If you just want to copy the top level of the list, you may use (APPEND 
expression). 
We might define COPY as follows: 


(DEFINEQ 
(copy (expression) 
(COND 
((NLISTP expression) 
(* 


If EXPRESSION is not a list, 
just return the value of 
EXPRESSION. 
) 
expression) ) 
(PROG (xlst ylst) 
(* 


) 
(SETQ ylst 
(LIST (COPY (CAR expression) ))) 


(SETQ xlst ylst) 


Copy the first element of expression. 


loop 
(SETQ expression (CDR expression) ) 
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(COND 
((NLISTP expression) 
(* 
Condition is satisfied when 
we reach the end of 
expression, since (NLISTP 
NIL) is T. 
(RPLACD ylst (COPY expression) ) 
(RETURN xlst))) 
(SETQ ylst 
(CDR 
(RPLACD ylst 
(RPLACD 
(CONS 
(COPY 
(CAR 
expression) ) 
ylst))))) 
(GO loop) ) 


)) 


6.4.2 Copying All List Elements 


COPY will not duplicate non-list elements when it copies an expression (see 
“seed” example above). Rather, it creates pointers to non-list elements such as 
arrays, strings, etc. COPYALL duplicates every element of a list including at- 
oms, arrays, and strings when you must have new copies of each element of the 
list. It takes the form 


Function: COPYALL 
HCOPYALL 
# Arguments: 1 
Argument: 1) an S-expression, EXPRESSION 
Value: A new copy of EXPRESSION including all 


non-list data structures. 
Consider the following examples: 


«(SETQ x1 "Merry Christmas") 
"Merry Christmas" 


«(SETQ x2 (COPYALL x1)) 
"Merry Christmas"! 
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—(EQ x1 x2) 
NIL 
(EQUAL x1 x2) 
r 


x2 
"Merry Christmas" 


«(SETQ y (ARRAY 3)) 
{ ARRAYP }#542224 


«(SETA y 1 100) 
100 


«(SETA y 2 200) 
200 


«(SETA y 3 300) 
300 


<(SETQ z (COPYALL y)) 
{ ARRAYP }#542231 


«(ELT z 2) 
200 


A variation, HCOPYALL, copies data structures that contain circular 
pointers. For example, 


<(SETQ rare-gases 

(LIST 'helium 'krypton ‘argon 'xenon 'radon)) 
(helium krypton argon xenon radon) 
Now let us create a circular list: 


«-(RPLACD (LAST rare-gases) rare-gases) 


The result of executing this function at the top level of INTERLISP is a 
repeating list of the form 


(helium krypton argon xenon radon helium krypton argon 
xenon radon ...) 


To terminate the printing, you must interrupt via CTRL-D to force a reset of 


the top level of INTERLISP. 
If we attempt to apply COPYALL to this circular list, we obtain 


«(SETQ inert-gases (COPYALL rare-gases) ) 
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This function never succeeds because COPYALL attempts to build up a list 
by successive references to elements of RARE-GASES. The ultimate result is to 
exhaust your virtual memory and cause INTERLISP to crash. 

However, if we apply HCOPYALL, we obtain 


<(SETQ inert-gases (HCOPYALL rare-gases) ) 
(helium krypton argon xenon radon . [1]) 


- where the strange notation indicates that INERT-GASES is circular just like 
RARE-GASES. 


6.4.3 Copying with Reversal 


REVERSE allows you to copy a list while reversing the order of its elements. It 
takes one argument, the list to be reversed, and returns the reversed list. It takes 
the form 


Function: REVERSE 
DREVERSE 
# Arguments: 1 
Argument: 1) an S-expression, EXPRESSION 
Value: A copy of EXPRESSION with all top-level 


elements reversed in sequence. 
Consider the following examples: 


«(REVERSE 'huckleberry) 
NIL 


because it does not operate upon non-lists. 


<-(REVERSE (LIST 'orange 'blue 'magenta 'yellow)) 
(yellow magenta blue orange) 


REVERSE will only reverse the top-level elements in a list. For example, 


«<(SETQ errors 
(LIST '(my blunder) 
'(his oversight) 
"(their negligence) )) 
((my blunder) (his oversight) (their negligence) ) 


«(REVERSE errors) 
((their negligence) (his oversight) (my blunder) ) 
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You may wish to define a function, REVERSEALL, that reverses a list at all 
levels. 

An alternative version, DREVERSE, destroys the original list and sets the 
reversed list as its value. It does not use any additional storage. 

REVERSE is useful in many situations, but particularly in those programs 
where you are simulating a stack or an agenda. 

Suppose you need to read a sentence into your program. Each sentence is 
terminated by a ! or a ? which indicates the type of processing to be applied to 
the sentence. We want to define a function GET-SENTENCE which reads atoms 
from the your terminal until it detects one of those two terminators. Its definition 
looks like this 


(DEFINEQ 
(get-sentence NIL 
(PROG (sentence) 
loop 
(SETQ sentence 
(CONS (RATOM) sentence) ) 


(COND 
((MEMBER (CAR sentence) '(! ?)) 
(RETURN 
(CONS (REVERSE sentence) 
NIL)))) 
(GO loop) ) 


)) 


We might define REVERSE as follows: 


(DEFINEQ 
(reverse (expression) 
(PROG (1st) 
loop 
(COND 
((NLISTP expression) 
(RETURN 1st) )) 
(SETQ 1st 
(CONS (CAR expression) lst) ) 
(SETQ expression (CDR expression) ) 
(GO loop) ) 


)) 


6.4.4 Removing Elements from a List 


To remove an element from a list, we must excise it from the front, back, or 
within the list. Removing an element from the front of the list is very simple—we 
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just return the CDR of the list. Removing an element from the rear is also simple 
because we can use RPLACA to assign NIL to the last element of the list. Re- 
moving an element from within a list is more difficult because we must search for 
the element and then delete it while adjusting the pointers from the surrounding 
elements. INTERLISP provides REMOVE to delete elements within a list. It 
takes the form 


Function: REMOVE 
DREMOVE 


# Arguments: 2 


Arguments: 1) an atom, X 
2) an S-expression, LST 


Value: A copy of LST with all top level elements 
equal to X removed from it. 


Consider the following examples: 


«(REMOVE 'a '(c rawdadd y)) 
(erwdddy) 
REMOVE can delete NIL from a list: 


“plaintext 
(EPLURIBUSUN UM) 


+(RPLACA (LAST plaintext) ) 
(NIL) 


“plaintext 
(EPLURIBUSUNU NIL) 


«(REMOVE NIL plaintext) 
(EPLURIBUSUNU) 


Note that REMOVE only removes the top-level elements equal to X. For 
example, 


«(REMOVE 'sheila '(sheila (sheila) )) 
((sheila) ) 


And removing the only element of a list makes that list become NIL. For 
example, 


«-(REMOVE 'apple-pie '(apple-pie) ) 
NIL 
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An alternative form, DREMOVE, uses EQ instead of EQUAL to delete X. 
Moreover, it actually modifies LST rather than returning a copy with X deleted. 
However, DREMOVE cannot change a list to NIL. For example, 


+(SETQ dessert '(apple-pie) ) 
(apple-pie) 

+-(DREMOVE 'apple-pie dessert) 
NIL 


«dessert 
(apple-pie) 


This execution of DREMOVE returns NIL, but it does not perform any 
CONSes. The value of DESSERT remains (apple-pie), because there is no way 
to change a list into a non-list. 

We might define REMOVE as follows: 


(DEFINEQ 
(remove (x lst) 
(COND 
((NLISTP lst) NIL) 
((EQUAL x (CAR lst)) 
(REMOVE x (CDR lst) )) 
(T 
(CONS (CAR lst) 
(REMOVE x (CDR l1st))))) 
)) 


6.5 MODIFYING LISTS BY SUBSTITUTION 


Lists are a generalized structure for representing information about problems. 
Often, the ordering of elements within a list has significant import to the inter- 
pretation of the list within a program. As program execution progresses, you 
may want to modify the structure of a list to replace old information with new 
values. One way is to modify the list itself by substituting new values for those 
that already exist in the list. 


6.5.1 A General Substitution Function: SUBST 
SUBST is the general INTERLISP substitution function. Its format is 
Function: SUBST 


DSUBST 
LSUBST 
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# Arguments: 3 


Arguments: 1) an S-expression, NEW 
2) an atom, OLD 
3) a list, LST 


Value: The new value of the list after 
substitution. 


SUBST evaluates its arguments. It performs a one-for-one substitution of 


the value of NEW for the value of OLD for all occurrences of OLD in LST when 


1. OLD is EQUAL to the CAR of some sublist of LST, 

2. When OLD is atomic and not NIL, 

3. When OLD is atomic, not NIL, and EQ to the CDR of some sublist of 
LST. 


For example, suppose we have a mathematical formula to evaluate that has 


placeholders for arguments. We need to substitute the variable names into the 
formula and then evaluate it. Consider the following example: 


<—(SETQ formula 
'(SQRT (PLUS (TIMES $x $x) (TIMES $y $y)))) 
(SQRT (PLUS (TIMES $x $x) (TIMES $y $y))) 


<(SETQ length 10) 
10 


<(SETQ height 20) 
20 


«(EVAL (SUBST 'length '$x 
(SUBST 'height '$y formula) )) 
22.36 


How was this accomplished? First, the substitution is performed to yield the 


S-expression to be evaluated. This is just a list that is given to EVAL to interpret. 
EVAL returns the value. The intermediate steps in the evaluation are 


(SUBST 'height '$y formula) yields a list of the form 
(SQRT (PLUS (TIMES $x $x) (TIMES height height))). 


This is then used by (SUBST ‘length ‘$x ...) to produce the list 


(SQRT (PLUS (TIMES length length) (TIMES height 
height) )). 
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This list is evaluated by EVAL. Note that LENGTH and HEIGHT in the 
final list are the names of variables that have values, as defined above, which are 
evaluated by EVAL to produce the result. 

The value of SUBST is a new list containing the appropriate changes to 
LST. If NEW is a list, its value is copied into the new list at each occurrence of a 
substitution. 

DSUBST is an alternative form of SUBST that does not copy LST but 
changes its structure. However, it does use a new copy of NEW. 


A Definition for SUBST 
We might define SUBST as follows: 


(DEFINEQ 
(subst (new old lst) 
(COND 
((NULL 1st) NIL) 
((NLISTP lst) 
(COND 
((EQ old lst) 
(COND 
((NLISTP new) new) 
(T (COPY new)))) 


( (COND 
((LITATOM 014d) 
(EQ old (CAR 
1st) )) 
(COND 
((NLISTP new) 
new) 
(T (COPY new) ))) 
(T 
(SUBST new old (CAR 
1st) ))) 
(SUBST new old (CDR 1st))))) 


)) 


6.5.2 Substituting by Segments: LSUBST 


LSUBST is similar to SUBST except that it substitutes “NEW” segments for 
OLD. That is, if the value of NEW is a list, when NEW is substituted for OLD in 
some LST, the elements of NEW become individual elements of LST. For exam- 


ple, 
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<-(SETQ sentence 
'(the boy sees the girl with the telescope) ) 
(the boy sees the girl with the telescope) 


<-(LSUBST '(loves) 'sees sentence) 
(the boy loves the girl with the telescope) 


<-(LSUBST '(the old man) 'boy sentence) 
(the old man sees the girl with the telescope) 


«-(LSUBST '(the green engine) 'john 'john) 
(the green engine) 


We might define LSUBST as follows: 


(DEFINEQ 
(1subst (new old lst) 
(COND 
((NULL 1st) NIL) 
((NLISTP 1st) 
(COND 
((EQ old 1st) new) 
(T 1st))) 
((EQUAL old (CAR l1st)) 
(NCONC (COPY new) 
(LSUBST new old (CDR l1st)))) 
(t 
(CONS 
(LSUBST new old (CAR l1st)) 
(LSUBST new old (CDR lst))))) 
)) 


If LST is empty, no substitution can be performed, so LSUBST merely re- 
turns NIL. If LST is not a list, and OLD is equal to LST, the value of NEW is 
substituted for LST. Thus, you may dissect a list component by seoipopent and 
replace individual elements. 


6.5.3 Substituting by Association: SUBLIS 


Given an expression consisting of many atoms composed into a complex struc- 
ture, you may want to perform wholesale substitution from one or more atoms in 
the expression. SUBLIS allows you to substitute for multiple atoms with one 
function invocation. It takes the form 


Function: SUBLIS 
# Arguments: 3 


6.5 Modifying Lists by Substitution 155 


Arguments: 1) an association list, ALST 
2) an S-expression, EXPRESSION 
3) a structure flag, FLAG 


Value: A new expression with the appropriate 
substitutions made according to ALST. 


ALST is a list of pairs having the form 
((<atom1) . «newatom1)) ... (<atomN) . <newatomN)) ) 


SUBLIS substitutes (newatom[i]) for each <atom[i]) that is found in the 
expression. For example, 


<—(SUBLIS '((A B)) '(A B AB A B)) 
((B) B (B) B (B) B) 


A new structure may be created if needed, or if FLAG is T. If FLAG is NIL, 
and there are no substitutions made, the value returned is EXPRESSION. 

SUBLIS and SUBPAIR (see below) substitute the identical structure into 
EXPRESSION (unless FLAG is T) while SUBST and LSUBST substitute cop- 
ies. Consider the following example: 


<—(SETQ fruits '(papaya guava) ) 

(papaya guava) 

<(SETQ cheeses '(edam gouda camembert) ) 
(edam gouda camembert) 


<-(DSUBLIS (LIST (CONS 'edam fruits)) cheeses) 
((PAPAYA GUAVA) GOUDA CAMEMBERT) 


<-(DSUBLIS (LIST (CONS 'gouda fruits)) cheeses T) 
((PAPAYA GUAVA) (PAPAYA GUAVA) CAMEMBERT) 


<—(EQ (CAR cheeses) fruits) 
ib 


“(EQ (CADR cheeses) fruits) 
NIL 


An alternative form of SUBLIS, DSUBLIS, modifies EXPRESSION rather 
than copying it. 
We might define SUBLIS as follows: 


(DEFINEQ 
(sublis (alst expression flag) 
(COND 
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(alst 
(SUBPR expression alst) ) 
(flag 
(* 
No substitutions; create new 
copy. 


) 
(COPY expression) ) 
(T expression) ) 


)) 


SUBPR is defined in the next section. SUBLIS may be used to implement a 
simple substitution cipher system. Let the association list entries have the form 


(<plaintext letter) (ciphertext letter)) 


The association list has 26 entries (assuming no numbers or special charac- 
ters). Consider the following key: 

Plaintext: 

ABCDEFGHIJKLMNOPQRSTUVWXYZ 

Ciphertext: 

DEFGHIJKLMNOPQRSTUVWXYZABC 
which is just the letters of the alphabet circulated by three characters. 

A function to encipher plaintext is just 


(DEFINEQ 
(encipher (text key) 
(SUBLIS key text T) 
)) 


Deciphering is done, of course, by reversing all of the entries in the key and 
applying it to the enciphered text. 

We may demonstrate this technique by applying it to several examples. 
First, let us define the key as follows: 


«(SETQ KEY 
(LIST '(A . D) '(B.E) '(C. F) '(D.G) '(E. H) 

VER or TY HG TD HHO AEB) 
1K s N) OYCL,. 6) SB) OG). 110-2) 
‘(Pp . 8) 110.7) RR. UY TG VY) Ps WD 
'(u . X) "\(v.. x) '(w.. Zz) '(X. A) N(Y . B) 
"(Z . C))) 

Cth + Dee (Bs Bante. 2B. son 
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+(SETQ plaintext '(EPLURIBUSUNUM)) 
(EPLURIBUSUN UM) 


+-(SETQ ciphertext (ENCIPHER plaintext key) ) 
(HSOXULEXVXQ XP) 


—(SETQ plaintext2 
'(TWASTHENIGHTBEFOREXMAS)) 
(TWASTHENIGHTBEFOREXMAS) 


«-(SETQ ciphertext2 (ENCIPHER plaintext2 key) ) 
(WZDVWKHQLJIKWEHIRUHAPDV) 


You may reverse the entries in the key using the following function 


(DEFINEQ 
(reverse-key (key) 
(MAPCAR key (FUNCTION REVERSE) ) 
)) 


To decipher the text derived above, you may use the expression 
<-(ENCIPHER ciphertext (REVERSE-KEY key) ) 
(EPLURIBUSUN U M) 

<-(ENCIPHER ciphertext2 (REVERSE-KEY key) ) 
(TWASTHENIGHTBEFOREXMAS) 


Note that each entry must be in the form of a CONS list. If each entry was a 
list of the form (A B), for example, then the resulting list produced by ENCI- 
PHER would appear as 


((H) (S) (0) (X) (U) (L) (E) (X) (V) (xX) (Q) (xX) (P)) 


6.5.4 Substituting by Pairing: SUBPAIR 


SUBPAIR operates like SUBLIS except that the old and new values are con- 
tained in separate lists. It takes the form 


Function: SUBPAIR 


# Arguments: 4 


Arguments: 1) a key list, OLD 
2) a replacement list, NEW 
3) an S-expression, EXPRESSION 
4) a structure flag, FLAG 


Value: The modified expression. 
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For each atom in OLD, SUBPAIR substitutes the corresponding atom in 
NEW for every occurrence in EXPRESSION. There are several cases: 


1. If OLD is an atom, the entire list NEW is substituted for it. For example, 
in creating a file header, you may specify a form for the File Package 
command as 


(FNS * <filefns)) 


where <filefns) is an atom whose value is a list of functions in the file. 
You may substitute the value of <filefns) for the atom in the form using 


«(SETQ fnsform (LIST 'FNS '* 'MYFNS)) 
(FNS * MYFNS) 


«-(SUBPAIR 'MYFNS MYFNS FNSFORM T) 
(FNS * MYFNS1 MYFNS2 MYFNS3 ...) 


and you may remove the asterisk (*) via DREMOVE (see Section 6.4.4). 


2. If (LENGTH OLD) is less than (LENGTH NEW) and OLD ends in an 
atom other than NIL, the remaining elements of NEW are substituted 
for the last element of OLD. For example, 


<(SUBPAIR '(ab.c) '(de fg) '(x ye w)) 
(x y (f g) w) 


because A is matched with D, B is matched with E, and (F G) is matched 
with C. 


3. If (LENGTH NEW) is less than (LENGTH OLD), then NIL is matched 
with each of the remaining atoms on OLD, For example, 


«(SUBPAIR '(a bc ad) '(x yz) '(c abb y)) 
(zxyyy) 


<(SUBPAIR '(a bec dad) '(x yz) '(daddy)) 
(NIL x NIL NIL y) 


As with SUBLIS, a new structure is created only if needed or if FLAG is T. 
That is, if FLAG is NIL, and no substitutions are performed, then the expression 
returned is EXPRESSION. 


We may use SUBPAIR instead of SUBLIS in our cryptographic example 
given above. We define two key lists as follows: 
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«(SETQ oldkey '(a be d...)) 
(aD ad ax) 


«-(SETQ newkey '(de f g ...)) 
(defg...) 


We modify the definition of ENCIPHER as follows: 


(DEFINEQ 
(encipher (oldkey newkey text) 
(SUBPAIR oldkey newkey text T) 
)) 


Then, we may apply it to an example: 


<(SETQ ciphertext (encipher oldkey newkey plaintext) ) 
(HAS OXUEK VX Q.xX'P) 


Note that we need only reverse the order of the keys in this definition of 
ENCIPHER in order to decipher the text. 


<(SETQ newplaintext (encipher newkey oldkey ciphertext) ) 
(EPLURIBUSUNU M) 


We might define SUBPAIR as follows: 


(DEFINEQ 
(subpair (old new expression flag) 
(COND 
(old 
(SUBPR expression 
old 
(RPLACA '((D E F)) new))) 
(flag 
(COPY expression) ) 
(T 
expression) ) 


)) 


Both SUBLIS and SUBPAIR make use of SUBPR to perform the hard work 
of substitution. SUBPR might be defined as follows: 


(DEFINEQ 
(subpr (expression lst1 1st2) 
(PROG (index dist alst) 
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(COND 
((NLISTP expression) 
- (COND 
((NULL 1st2) 
(* 
Called from 
SUBLIS. 
LST2 is NIL. 


) 
(GO loop2))) 
(SETQ lst2 (CAR 1st2) ) 
(SETQ index 1) 
(GO loop) ) 
((SETQ dlst (CDR expression) ) 
(SETQ dlst 
(subpr (CAR expression) 
1lsti 
1st2)))) 
(SETQ alst 
(subpr (CAR expression) 
lsti 
1st) ) 
(RETURN 
(COND 
((OR flag 
(NEQ alst (CAR expression) ) 
(NEQ dist (CDR 
expression) )) 
(CONS alst dlst)) 
(T expression) )) 
loop 
(* 
Searching for LST1 element in 
expression. 


) 
(COND 
((NULL 1st1) 
(RETURN expression) ) 
((NLISTP 1st1) 
(COND 
((EQ expression 1st1) 
(GO loop1))) 
(RETURN expression) ) 
((EQ expression (CAR 1st1)) 
(GO loop1))) 


)) 
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(SETQ index (ADD1 index) ) 

(SETQ 1lsti (CDR 1st1)) 

(GO loop) 

loop1 

(* 
At this point, we have found an 
element in expression from LST1; now 
find corresponding element in LST2. 


) 
(COND 
((EQ index 1) 
(SETQ lst2 
(COND 
((NLISTP 1lst1) 1lst2) 
(T (CAR 1st2)))) 
(RETURN 
(COND 
(flag (COPY lst2)) 
(T 1st2))))) 


(SETQ index (SUB1 index) ) 
(SETQ lst2 (CDR 1st2)) 
(GO loop1) 
loop2 
(COND 
((EQ (CAAR 1lst1) expression) 
(RETURN 
(COND 
(flag (COPY (CDAR 
1st1))) 
(T (CDAR 1st1))))) 
((NULL (SETQ lst1 (CDR 1st1))) 
(RETURN expression) ) ) 
(GO loop2) ) 


6.6 LOGICAL OPERATIONS ON LISTS 


A set, in mathematical terms, is an unordered collection of items. Typically, sets 
contain only numbers which may be mathematically manipulated. Because IN- 
TERLISP is a symbolic processing language, sets may contain symbolic infor- 


mation. 


A set may be represented as a list. To add an item to a set, we CONS or 
NCONC it to the list. Deletion of an item is effected by CAR or some other func- 


tion. 
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Set theory defines a number of primitive operations on sets: difference, in- 
tersection, and union. INTERLISP provides functions that operate on lists as if 
they were sets. In the following sections, we describe these primitive functions. 
Then, we look at additional set functions that may be written using them. 


6.6.1 Logical Difference 
The logical difference of two sets, X and Y, is a list consisting of those elements 
of X that are not members of Y. Consider the following example: 

<(SETQ states (LIST 'AL 'MD 'NY 'SD 'CA 'IL 'HI 'CT)) 

(AL MD NY SD CA IL HI CT) 


«(SETQ eastern-states (LIST 'AL 'MD 'NY 'CT)) 
(AL MD NY CT) 


«(LDIFFERENCE states eastern-states) 
(SD CA IL HI) 


«(LDIFFERENCE eastern-states states) 
NIL 


Note that LDIFFERENCE is not a commutative function. LDIFFERENCE 
takes the form 


Function: LDIFFERENCE 
# Arguments: 2 
Arguments: 1) a list, IST? 
2) a list, LST2 
Value: The difference between the two lists 


formed by extracting all elements of the 
first list from the second. 


We might define LDIFFERENCE as follows: 


(DEFINEQ 
(ldifference (l1st1 1lst2) 
(COND 
((OR 

(NULL 1st1) 

(NULL 1st2)) 

(* 
If either list is empty, the 
logical difference with NIL is 
NIL. 
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NIL) 
ee (CAR 1lst1) 1st2) 
* 


Compare the lists by matching 
down LST1; use recursion. 


(ldifference (CDR lst1) 1lst2)) 


(* 


(T 


The element is not a member of 
LST2, so add it to the list of 
differences. 


(CONS (CAR 1st1) 
(ldifference (CDR lst1) 
é 1st2)))) 
) 


Note that LDIFFERENCE returns a new list containing only the members 
of LST1 which are not found in LST2. 


LDIFF: Computing the Difference to a Tail 

LDIFF computes the difference between LST1 and LST2. LST2 must be a 
proper tail of LST1. That is, LST2 is derived by applying CDR some number of 
times to LST1. Thus, we obtain a list of differences between LST1 and LST2 up 
to LST2 in LST1. It takes the form 


Function: LDIFF 
# Arguments: 3 


Arguments: 1) @ list, LSTi 
2) a list which is a tail of LST1, LST2 
3) a result list, LST3 


Value: The differences between LST1 and LST2. 


If LST3 is not NIL, then the differences between LST1 and LST2 are 
NCONCed onto LST3. This provides a mechanism for gathering the differences 
among a number of lists into a single list. 

Consider the following example: 


<(SETQ os '(vms unix vulcan aos multics mvs) ) 
(vms unix vulean aos multics mvs) 


+(SETQ bigos (NLEFT os 1 (LAST os))) 
(multics mvs) 
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«(LDIFF os bigos) 
(vms unix vulcan aos) 


«-(LDIFF os bigos '(cp/m ms-dos) ) 
(cp/m ms-dos vms unix vulcan aos) 


«-(LDIFF os '(mep tenex) ) 
LDIFF: NOT A TAIL 
(mep tenex) 


«(LDIFF os) 
(vms unix vulcan aos multics mvs) 


«<(LDIFF os os) 
NIL 


«<(LDIFF os os '(cp/m ms-dos) ) 
(cp/m ms-dos) 


LDIFF always returns a new list structure unless LST2 is NIL, in which case 
the value is LST1. 

If LST2 is not a tail of LST1, LDIFF generates an error message ““LDIFF: 
NOT A TAIL”. LDIFF will terminate on a null check. However, if LST1 is a 
circular list and LST2 is not a tail, LDIFF goes into an infinite loop. 

We might define LDIFF as follows: 


(DEFINEQ 
(ldiff (lst1i lst2 1st3) 
(COND 
((EQUAL 1lst1 1st2) 
(* 
No differences; return LST3 
) 
1st3) 
((AND (NULL lst2) (NULL 1st3)) 
(* 
LST2 is null; return LST1 
) 
1st1) 


(PROG (diflst) 
(* 
DIFLST is the difference list, 
which is initialized to LST3, if 
present. 


) 
(SETQ diflst (LAST 1st3)) 
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(SETQ diflst 
(CDR 
(RPLACD diflst 
(RPLACD 
(CONS (CAR 1st1) 
diflst))))) 
(COND 
(1st3 diflst) 
(T 
(SETQ diflst 
(SETQ 1st3 
(CONS (CAR 
1st1)))))) 
loop 


(SETQ lst1 (CDR 1sti)) 
(COND 
((EQ lst1 1st2) 
(* 

If lists are 
identically equal, 
there is no 
difference, so return 
LST3. 


) 
(RETURN 1st3) ) 
((NULL 1st1) 


(* 
Obviously, LST2 cannot 
be a tail of the null 
list. But, when we 
reach here, we have 
also exhausted LST1. 
) 
(RETURN 
(ERROR "LDIFF: NOT A 
TAIL" 
1st2)))) 
(SETQ diflst 
(CDR 
(RPLACD diflst 
(RPLACD 
(CONS (CAR 1st1) 
diflst))))) 


(GO loop) ))) 
)) 
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6.6.2 Logical Intersection 


The intersection of two sets, X and Y, is a set consisting of those elements that 
are members of both X and Y. Consider the following example: 


«(INTERSECTION states eastern-states) 
(AL MD NY CT) 


«-(INTERSECTION eastern-states states) 
(AL MD NY CT) 


Note that INTERSECTION is a commutative function; that is, the order of 
the arguments does not affect the result. 


INTERSECTION takes the form: 
Function: INTERSECTION 
# Arguments: 2 | 
Arguments: 1) a list, LST1 
2) a list, LST2 
Value: A list containing elements that appear 


either in LST1 or LST2. 


We might define INTERSECTION as follows: 


(DEFINEQ 
(intersection (lst1 lst2) 
(COND 
((OR 

(NULL 1st1) 

(NULL 1st2)) 

(* 
No intersection with the null 
List. 


NIL) 
((MEMBER (CAR 1st1) lst2) 
* 


Here we begin to construct the 
list to be returned. We always 
choose an element from LST1. 


(CONS (CAR lst1) 
(intersection (CDR 1st1) 
1st2) )) 
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(T 


,) (intersection (CDR lst1) 1st2))) 


Note that INTERSECTION does not check for duplicates in LST1. Thus, if 
there are two elements with the same value in LST1, both elements will appear in 
the result if there is at least one corresponding element in LST2. Sometimes, we 
want to work with unique sets, e.g., those where there is at most one element of a 
given value in the set. We can define the function UNIQUE to produce this set as 
follows: 


(DEFINEQ 
(unique (x) 
(intersection x x) 
)) 


Consider the following example: 


<(SETQ states (LIST 'AL 'NY 'CT 'MI 'AL 'FL 'CT)) 
(AL NY CT MI AL FL CT) 


“(UNIQUE states) 
(AL NY CT MI FL) 


6.6.3 Logical Union 


The union of two sets, X and Y, is a set consisting of all elements that appear in 
either X or Y. Consider the example: 


«(SETQ northern-states (LIST 'MD 'NY 'PA 'RI)) 
(MD NY PA RI) 


«(UNION eastern-states northern-states) 
(AL CT MD NY PA RI) 


«(UNION northern-states eastern-states) 
(PA RI AL MD NY CT) 


The order of the arguments makes a profound difference in the result. You 
should consider this carefully if your application depends on the list elements 
occurring in a particular order. 

Note that UNION is not commutative. Its value is a new list consisting of the 
elements of Y with all elements of X that are not members of Y CONSed to the 


front. UNION takes the form 
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Function: UNION 
# Arguments: 2 
Arguments: 4). & List, LSTi 
2) "a Uist; LST2 
Value: if list which is the union of LST1 and 


We might define UNION as follows: 


(DEFINEQ 
(union (lst1 1st2) 
(COND 
((NULL 1sti) 1st2) 
((MEMBER (CAR 1st1) 1st2) 
(union (CDR 1lst1) 1st2)) 
(T 
(CONS (CAR 1st1) 
(union (CDR 1lst1) 1st2)))) 
)) 


Note that if an element appears twice in LST2, it will also appear twice in the 
UNION of LST1 and LST2. Sometimes, we want the unique union of two sets. 
We may define a function to produce the unique union as follows: 


(DEFINEQ 
(unique-union (x y) 
(intersection (union x y)) 
)) 


6.7 SORTING LISTS 


Most lists are constructed without regard to the ordering of the elements. Some 
applications, however, require a list to be sorted according to some criterion 
before processing. 

Sorting is the process by which a list of items, normally disordered, is placed 
in order according to some criterion based on the contents of the list. For unor- 
dered lists, there is no better procedure than a serial search. If the list does not 
contain the item sought, we must search the entire list to determine this fact. If 
the list is ordered, however, certain techniques greatly reduce the searching ef- 
fort to determine if the item is present. This section will present a number of 
sorting functions using different algorithms. Further information on sorting 
may be obtained from Knuth [knut68] and Aho, Hopcroft, and Ullman [aho83]. 
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6.7.1 A Basic Sorting Function 


INTERLISP provides the basic function SORT to sort lists. It sorts lists by a 
brute force method of comparing two items in the list at a time. It has the format 


Function: SORT 
# Arguments: 2 


Arguments: 1) a list of items to be sorted, ITEMS 
2) a comparison function, FNCOMPARE 


Value: A sorted list comprised of the items on 
the source list. 


SORT uses the function specified by FNCOMPARE, which must be a predi- 
cate with two arguments, to compare two data items. FRCOMPARE must re- 
turn T if its first argument belongs before the second, otherwise NIL. 

If FRCOMPARE is NIL, SORT uses ALPHORDER (see Section 6.7.3) to 
lexically order items. Consider the following example: 


«(SETQ states (LIST 'WA 'MD 'AL 'FL 'CO 'ND 'HI)) 
(WA MD AL FL CO ND HI) 


(SORT states) 
(AL CO FL HI MD ND WA) 


SORT expects the elements of ITEMS to be atomic values. However, SORT 
allows you to sort a list whose elements are themselves lists. In this case, the CAR 
of each list must be atomic. It is passed to ALPHORDER to determine the order 
of arrangement. To specify this invocation, you must set FRCOMPARE to T. 
Consider the following example: 


«(SETQ items '((x 1.0) (b 2.3) (j 3.7) (f 0.4) (q 6.3))) 
((x 1.0) (b 2.3) (j 3.7) (f 0.4) (q 6.3)) 


<(SORT items T) 
((b 2.3) (f 0.4) (j 3-7) (q 6.3) (x 1.0)) 


SORT is a destructive function. That is, it modifies the list given as its argu- 
ment rather than creating a new list. Thus, if the initial ordering of the input list 
is also important, you should copy the input list before sorting. 

We might define SORT as follows: 


(DEFINEQ 
(sort (items fncompare) 
(PROG (result nxtitems olditems) 
(SETQ olditems items) 
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(SETQ items 
(CONS (CAR items) 
(CDR items) )) 
loop ‘ 
(SETQ nxtitems (CDDR items) ) 
(SETQ result 
(CONS 
(MERGE1 (RPLACD (CDR items) ) 
(RPLACD items) 
fncompare) 
result) ) 
(AND 
(SETQ items nxtitems) 
(GO loop) ) 
(SETQ items result) 
loop2 
(SETQ nxtitems items) 
loop1 
(COND 
(nxtitems 
(RPLACA nxtitems 
(MERGE1 (CAR nxtitems) 
(CADR nxtitems) 
fncompare) ) 
(RPLACD nxtitems 
(CDDR nxtitems) ) 
(SETQ nxtitems 
(CDR nxtitems) ) 
(GO loop1))) 
( AND 
(CDR items) 
(GO loop2) ) 
(RPLACA olditems (CAAR items) ) 
(RPLACD olditems (CDAR items) ) 
(RETURN olditems) ) 


)) 


MERGE 1 is defined in Section 6.9. 


6.7.2 Numeric Sorting 


A common application for sorting is to arrange a set of numbers in ascending or 
descending sequence. We might write a function NUMERIC-SORT as follows 
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(DEFINEQ 
(numeric-sort (items flag) 
(SELECTQ flag 
(ascending (SORT items (FUNCTION 
GREATERP) ) ) | 
(descending (SORT items (FUNCTION LESSP) )) 
(PROGN 
(PRIN1 "unknown flag'') 
)) (TERPRT) ) ) 


6.7.3 Alphameric Sorting 


ALPHORDER is a predicate function that is used when sorting lists according 
to their alphabetical sequence. It takes the form 


Function: ALPHORDER 
# Arguments: 2 


Arguments: 1) an atom, X 
2) an atom, Y 


Value: T, if X occurs before Y; otherwise, NIL. 


ALPHORDER determines if X occurs before Y. X and Y may be numbers, 
atoms, or strings. Numbers come before literal atoms and are ordered by magni- 
tude (using GREATERP). Literal atoms and strings are ordered by comparing 
the character codes of their PRIN1-names. Consider the following examples: 


«-(ALPHORDER 'newton 'benatar) 
NIL 


<(ALPHORDER 3.141592 3.141593) 
a. 


«(ALPHORDER ''Interlisp-10'' "Interlisp/VAX") 
. 


If neither X nor Y is an atom or a string, ALPHORDER returns T; that is, 
they are presumed in order because ALPHORDER can make no determination. 


For example, 


-(SETQ Al (ARRAY 3 3)) 
{ ARRAYP }#542224 
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«(SETQ A2 (ARRAY 5 5)) 
{ ARRAYP }#542231 


“(ALPHORDER A2 A1) 
T 


even though it is clear, by inspection, that Al occurs physically in memory before 
A2. 
We might define ALPHORDER as follows: 


(DEFINEQ 
(alphorder (x y) 
(COND 
((FIXP x) 
(COND 
((FIXP y) 
(IGREATERP y x)) 
((FLOATP y) 
(FGREATERP y x)) 
(T T))) 
((FLOATP x) 
(COND 
((FIXP y) 
(FGREATERP (FLOAT y) x))) 
((FLOATP y) 
(FGREATREP y x)) 
(T T))) 
((LITATOM x) 
(COND 
((NUMBERP y) NIL) 
((LITATOM y) 
(PROG (index xlen ylen xchar 
yehar) 
(SETQ index 0) 
(SETQ xlen (NCHARS x)) 
(SETQ ylen (NCHARS y)) 
loop 
( AND 
(EQ index xlen) 
(RETURN T)) 
( AND 
(EQ index ylen) 
(RETURN NIL) ) 
(SETQ index (ADD1 index) ) 
(SETQ xchar 
(NTHCHAR x index) ) 
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(SETQ ychar 
(NTHCHAR y index) ) 
(COND 
((EQ xchar ychar) 
(GO loop) )) 
(RETURN 
( IGREATERP 
(CHCON xchar) 
(CHCON ychar))))) 
(T T))) 
(T T)) 
)) 


The IRM [irm83] notes that ALPHORDER performs no UNPACKs, 
CHCONSs, or NTHCHARs (even though we show it might be coded above using 
these functions!). Thus, it is several times faster than anything that can be writ- 
ten using these other functions. ALPHORDER is actually implemented in ma- 
chine language or microcode, but the definition given above (for INTERLISP/ 
370) suggests how it works. 

In FranzLisp, this function is known as ALPHALESSP. 


6.7.4 Comparing Two Lists 


ALPHORDER does not work on lists. Sometimes, we may need to compare two 
lists to determine their differences. COMPARELISTS is a function that com- 
pares two lists and prints their differences. Printing is inherent in the operation 
of COMPARELISTS. It takes the form 


Function: COMPARELISTS 


# Arguments: 2 


Arguments: 1) a list, LST1 
2) a list, LST2 


Value: NIL, but it prints the differences between 
the two lists. 


Consider the following example: 


<(COMPARELISTS os bigos) 
(vms unix vulcan --) 
(multics mvs) 


Note that COMPARELISTS is subject to the influence of PRINTLEVEL 
(see Chapter 15). 
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We might define COMPARELISTS as follows: 


(DEFINEQ 
(comparelists (lst1 1st2) 
(RESETFORM (PRINTLEVEL 1) 
(PROG (finish) 
(COND 
((EQUAL lst1 1st2) 
(RETURN NIL) ) 
( (AND 
(NLISTP 1st1) 
(NLISTP 1st2) 
(GETD 1st1) 
(GETD lst2)) 
(SETQ lst1 (GETD 
1st1) ) 
(SETQ lst2 (GETD 
1st2)))) 
(COND 
((OR 
(NLISTP 1sti) 
(NLISTP 1st2)) 
(PRINT lst1 T) 
(PRINT lst2 T) 
(GO finish) )) 
(PRIN1 "(" T) 
(* 
Print LST1 by comparison 
with LST2. 


(CMPLISTS lst1 1st2) 
(PRIN1 '')'' T) 
(TERPRI T) 

(PRIN1 "("' T) 

(* 


And vice versa. 


(CMPLISTS lst2 1st1) 
(PRIN1 '')" T) 
(TERPRI T) 
finish 
. (RETURN T))) 


where CMPLISTS is defined as 
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(DEFINEQ 
(emplists (xlst ylst) 
(PROG (x y flag dotflag) 
loop1 
(COND 
((NOT dotflag) 
(SETQ x (CAR xlst)) 
(SETQ y (CAR ylst))) 


(T 
(SETQ x xlst) 
(SETQ y ylst))) 
(COND 
(flag 
(COND 
(dotflag (PRINI "." T)) 
(T (PRIN1 " " T))))) 
(COND 


((EQUAL x y) 
(x 


If the two lists are the 
same, just print a &. 


) 


(PRIN2 
(COND 
((ATOM x) x) 
(T '&)) 
T)) 
((OR 
(NLISTP x) 
(NLISTP y)) 
(* 
If they are unequal 
and one is not a list, 
have PRIN2 display 
something at the 
terminal. 
) 
(PRIN2 x T)) 
(T 
(* 


Otherwise, print '"()" and 
recurse to analyze the 
sublists. 


) 
(PRIN1 "("' T) 
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(CMPLISTS x y) 
’ (PRIN1 "')"' T))) 
(SETQ flag T) 
(* 


FLAG causes CMPLISTS to print ''--'' 
if lists are of different lengths; 
otherwise, just the CDR. 


(COND 
(dotflag 
(RETURN NIL))) 
(COND 


((NULL (CDR xl1st) ) 
(RETURN NIL) )) 
(SETQ dotflag (NLISTP (CDR xlst))) 
(COND 
((NULL (CDR ylst)) 
(* 


If YLST expires first, 
print the tail of XLST. 


(COND 
(dotflag 
(PRINi " . " T) 
(PRIN2 
(COND 
((ATOM (CDR x1st)) 
(CDR xlst)) 
(T '&)) 
T)) 
((NULL (CDDR xlst)) 
(SPACES 1 T) 
(PRIN2 
(COND | 
((ATOM (CADR xlst)) 
(CADR xlst) ) 
(T '&)) 
T)) 


(PRIN1 " --"' T))) 
(RETURN NIL))) 
(SETQ xlst (CDR xlst)) 
(SETQ ylst (CDR ylst)) 
(GO loop1)) 


(T 
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Note that DOTFLAG handles the case where the last element of the list is 
really a dotted pair. 
6.8 LENGTH FUNCTIONS 


An essential feature of INTERLISP is that you almost never need to know the 
length of a list when you are writing your program. There usually comes a time, 


however, when you must know the length of a list. INTERLISP provides three 
functions for determining length. 


6.8.1 Finding the Length of a List 
LENGTH determines the length of its argument. It takes the form 


Function: LENGTH 

# Arguments: 1 

Argument: 1) an S-expression, EXPRESSION 

Value: The length of the list EXPRESSION as an 
integer. 


The length is determined by taking successive CDRs until a non-list is 
found. For example, 


«(LENGTH '(Cavendish Rutherford Becquerel Curie 
Roentgen) ) 
5 


(LENGTH NIL) 
0 


because NIL is an atom. 


«(LENGTH 'yankees) 
0 


because atoms are lists of zero length. 


«(LENGTH '(austin dallas fort-worth) ) 
3 


«(LENGTH '(austin dallas fort-worth . galveston) ) 
3 


because GALVESTON has been CONSed onto the list and so it occupies a CDR 
cell. 
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LENGTH is usually hardwired into the virtual machine for efficiency. How- 
ever, we might define it as follows: 


(DEFINEQ 
(length (expression) 
(COND 

((NULL expression) 0) 

((ATOM expression) 0) 

(T 

(ADD1 (LENGTH (CDR expression) )))) 

)) 


6.8.2 Counting List Cells 


LENGTH works only on the top-level elements of a list. Some algorithms may 
need to know the total number of cells occupied by a list. These include al- 
gorithms that must recursively process sublists of list elements where the time 
required to execute the algorithm is on the order of the size of the list. Various 
parsing algorithms fall into this category. 

COUNT determines the total number of list cells occupied by its argument. 
It takes the form 


Function: COUNT 

# Arguments: 1 

Argument: 1) an S-expression, EXPRESSION 
Value: The number of list cells required to 


represent EXPRESSION as an integer. 


In effect, it applies LENGTH not only to each element of a list but also to 
each sublist which is an element. COUNT applied to a non-list is 0. Consider 
these examples: 


<- (COUNT NIL) 
0 


«(COUNT (CONS 'braves 'brewers) ) 
1 


«(COUNT (LIST 'hayes-roth 'lenat 'brown 'feigenbaum) ) 
4 


«(COUNT ''Does it believe in strings?"') 
0 


“(COUNT (ARRAY 10)) 
0 
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and let’s look at a complex example: 


—(SETQ structure 
'(noun-phrase 
((3 (1000 frame (person sex male) 
startframe) ) ) 
NIL 
(noun-phrase-head NIL 
(numpers (1 3))) he)) 


«(LENGTH structure) 
5 


«(COUNT structure) 
22 


We might define COUNT as follows: 


(DEFINEQ 
(count (expression) 
(COND 

((OR 
(NULL expression) 
(ATOM expression) 
(NLISTP expression) ) 
0) 

(T 
(PLUS 


(COND 
((LISTP (CAR expression) ) 
(COUNT (CAR expression) ) ) 
(T 1)) 
(COUNT (CDR expression) )))) 


)) 


6.8.3 Counting Down a List 


When you apply COUNT to a list, you must “touch” every list cell in the list in 
order to determine the total number. Moreover, COUNT counts every cell in the 
list. Many times, you merely want to know if a list occupies a minimum number 
of list cells. COUNTDOWN operates like COUNT in that it counts list cells. It 


takes the form 


Function: COUNTDOWN 
# Arguments: 2 
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Arguments: 1) an S expression, EXPRESSION 
2) a limit, LIMIT 
Value: Either the number of list cells in X or 0. 


COUNTDOWN counts the list cells that comprise EXPRESSION. It decre- 
ments LIMIT as it touches each list cell. COUNTDOWN stops when 


1. LIMIT is decremented to 0, whence 0 is returned. This indicates the list 
has at least LIMIT cells. 


2. The end of EXPRESSION is reached while LIMIT is greater than 0. The 
value returned is equivalent to 


(IDIFFERENCE limit (COUNT expression) ) 
Consider the following examples: 


“(COUNTDOWN (DOCOLLECT 1 NIL) 100) 
0 


«(COUNTDOWN (FOR I FROM 1 TO 10 COLLECT (CONS I)) 50) 
30 


where the CLISP statement would yield 


((1) (2) (3) (4) (5) (6) (7) (8) (9) (10)). 


«(COUNTDOWN (CONS 'baltimore 'maryland) 10) 
9 


«(COUNTDOWN (LIST 'crimson 'red 'magenta 'ochre 'purple) 6) 
1 


Using COUNTDOWN, you may determine how far EXPRESSION has 
grown toward a predefined limit. This measurement may be used in state space 
search algorithms where the order of the size of EXPRESSION, which may be a 
representation of the problem states, is a measure of algorithm efficiency. In this 
case, we are concerned not only with the LENGTH of EXPRESSION but also 
the amount of memory that it consumes. 

Note also that COUNT will not work with circular lists as it continually cy- 
cles through the list. Using COUNTDOWN, you may place a bound on the num- 
ber of cells to be counted and determine the size of the list relative to that bound. 


6.9 MERGING LISTS 


In its simplest form, merging is the process of taking two ordered lists and creat- 
ing a single ordered list out of them. Knuth [knut68] and Aho, Hopcroft, and 
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Uliman [aho83] present additional material on the theory of merging and a 
number of different algorithms for merging two or more lists. INTERLISP pro- 
vides two basic functions for merging lists: MERGE and MERGEINSERT. 


6.9.1 Merging Two Lists 


MERGE destructively combines two sorted lists, X and Y, into a single new list. 
It takes the format 


Function: MERGE 
# Arguments: 3 


Arguments: 1) a sorted list, X 
2) a sorted list, Y 
3) a comparison function, FNCOMPARE 


Value: A list comprising the destructive merger 
of X and Y. 


MERGE uses FNCOMPARE to merge the elements of the sorted lists X and 
Y. FNCOMPARE must be the same function that was used to sort both X and 
Y. Consider the following examples: 


<(SETQ x (FOR I FROM 1 TO 10 (COLLECT (RAND O 1000))) 
(844 606 642 606 538 92 883 49 110 865) 


«-(SETQ y (FOR I FROM 1 TO 10 (COLLECT (RAND 0 1000))) 
(533 100 258 677 401 405 104 279 722 926) 


«(SORT x (FUNCTION IGREATERP) ) 
(833 865 844 642 606 606 538 110 92 49) 


«(SORT y (FUNCTION IGREATERP) ) 
(926 722 677 533 405 401 279 258 104 100) 


«-(MERGE x y (FUNCTION IGREATERP) ) 
(926 883 865 844 722 677 642 606 606 538 533 405 401 279 
258 110 104 100 92 49) 


+ (MERGE x y (FUNCTION LESSP) ) 
(883 865 844 642 606 606 538 110 92 49 926 722 677 533 
405 401 279 258 104 100) 


where we see the lists are not merged because the comparison function is differ- 
ent from the one used to sort the two lists. 


«(MERGE x y) 
(883 865 844 642 606 606 538 110 92 49 926 722 677 533 
405 401 279 258 104 100) 
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because the comparison function is NIL, so alphabetical order is used to com- 
pare the elements of the lists. 
We might define MERGE as follows: 


(DEFIN 
(merge (x y fncompare) 
~ (COND 
((NULL x) y) 
((NULL y) x) 
((NLISTP x) 


(ERROR "ARG NOT A LIST" x)) 
((NLISTP y) 
(ERROR "ARG NOT A LIST" y)) 
(T 
(SETQ fncompare 
(MERGE1 (CONS (CAR x) (CDR x)) 
(CONS (CAR y) (CDR y)) 
fncompare) ) 
(RPLACA 
(RPLACD y (CDR fncompare) ) 
(CAR fncompare) ) 
(RPLACA 
(RPLACD x (CDR fncompare) ) 
(CAR fncompare) ) )) 
)) 


MERGE 1 is defined as follows: 


(DEFINEQ 
(merge1 (x y fncompare) 
(PROG (result last) 
(OR x (RETURN y)) 
(OR y (RETURN x)) 


(COND 
((SELECTQ fncompare) 
(NIL 
(ALPHORDER (CAR x) (CAR y))) 
(T 
(ALPHORDER (CAAR x) (CAAR y))) 
(APPLY* fncompare (CAR x) (CAR y))) 
(SETQ result x) 
(SETQ x (CDR x))) 
(T 


(SETQ result y) 
(SETQ y (CDR y)))) 





loop 


)) 
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(SETQ last result) 
(COND 
((NULL x) 
(RPLACD last y) 
(RETURN result) )) 
(COND 
((NULL y) 
(RPLACD last x) 
(RETURN result) )) 


(COND 
((SELECTQ fncompare) 
(NIL 
(ALPHORDER (CAR x) (CAR y))) 
Hs 
(ALPHORDER (CAAR x) (CAAR y))) 
(APPLY* fncompare (CAR x) (CAR y))) 
(RPLACD last x) 
(SETQ last x) 
(SETQ x (CDR x)) 
(COND 
((NULL x) 
(RPLACD last y) 
(RETURN result) ))) 
(T 
(RPLACD last y) 
(SETQ last y) 
(SETQ y (CDR y)) 
(COND 
((NULL y) 
(RPLACD last x) 
(RETURN result) )))) 
(GO loop) ) 


6.9.2 Merging with Insertion 


Given a sorted list, X, we often want to insert an item into that list. MERGEIN- 
SERT inserts a single item into a sorted list. It takes the format 


Function: 
# Arguments: 
Arguments: 


MERGEINSERT 


3 


1) a new item, NEW 
2) a sorted list, X 
3) a flag, ONEFLAG 
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Value: A sorted list with the new element 
inserted at the proper location. 


MERGEINSERT attempts to place the new item, NEW, into the list X in 
the “best” possible position. Insertion is destructive; that is, X is physically 
modified. Consider the following example: 


«-(SETQ players '(cobb evers robinson tinker wagner) ) 
(cobb evers robinson tinker wagner) 
«(MERGINSERT 'ruth players) 


(cobb evers robinson ruth tinker wagner) 


Usually, we do not want to insert an item into a list if it is already present. If 
ONEFLAG is T, MERGEINSERT will not modify the list if NEW is already 
present. For example, 


<-(MERGEINSERT 'evers players T) 
(cobb evers robinson ruth tinker wagner) 


6.10 ASSOCIATION FUNCTIONS 


A common use of lists is to relate one value to another value or list of values. 
Usually, this takes the form ({key) <result)). KEY is the item to be searched for 
while RESULT is the value sought. If the result is a pointer, these are sometimes 
called inverted file indices. INTERLISP calls lists of this form association lists 
because they represent an association between a key and a result. The primary 
problem with using association lists is searching them. 


6.10.1 Searching Lists for Associations 


ASSOC searches a list of entries for an item. It returns a list consisting of the 
item and its associated value. ASSOC takes the form 


Function: ASSOC 
SASSOC 


# Arguments: 2 


Arguments: 1) a search item, KEY 
2) an association list, ALST 


Value: The entry or NIL. 


The association list is a list of zero or more entries where each entry has the 
form (usually a dotted pair) 


(<key) . <result)) 
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ASSOC searches ALST one entry at a time. It compares the CAR of each 
entry with KEY. If they are EQ, ASSOC returns the entry. Otherwise, it returns 
NIL. For example, 


<(SETQ games 
(LIST (CONS 'bridge 'cards) 

(CONS 'baccarat 'cards) 

(CONS 'chess 'men) 

(CONS 'craps 'dice) 

(CONS 'scrabble 'letters))) 
((bridge . cards) (baccarat . cards) (chess . men) (craps . 
dice) (scrabble . letters) ) 


«(ASSOC 'chess games) 
(chess . men) 


<(ASSOC 'backgammon games) 
NIL 


Because ASSOC uses EQ to compare the key against the CAR of each entry, 
the keys must be atoms. 

An alternative form, SASSOC, takes the same arguments but uses EQUAL 
for the comparison. For example, 


«-(SETQ games 
(LIST (LIST (LIST 'pridge) 'cards) 

(LIST (LIST 'baccarat) 'cards) 

(LIST (LIST 'chess) 'men) 

(LIST (LIST 'craps) 'dice) 

(LIST (LIST 'scrabble) 'letters) )) 
(((bridge) cards) ((baccarat) cards) ((chess) men) 
((craps) dice) (scrabble) letters) ) 


«(ASSOC '(bridge) games) 
NIL 


«(SASSOC '(bridge) games) 
((bridge) cards) 


We might define ASSOC as follows: 


(DEFINEQ 
(assoc (key alst) 
(PROG NIL 
loop 
(COND 
((NLISTP alst) 
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(COND 
((NULL alst) 
. (RETURN NIL)))) 
((EQ (CAAR alst) key) 
(RETURN (CAR alst)))) 
(SETQ alst (CDR alst)) 
(GO loop) ) 
)) 


6.10.2 Replacing an Association List Value 


There are three maintenance operations that we can perform on association lists: 


1. Adding a new entry 
2. Replacing the value associated with a key 
3. Removing an entry 


The latter case defaults to setting the value associated with a key to NIL. 
PUTASSOC is used for maintaining association lists. It takes the form 


Function: PUTASSOC 
# Arguments: 3 


Arguments: 1) a search item, KEY 
2) a value, VALUE 
3) an association list, ALST 


Value: The new value. 


PUTASSOC searches the association list using ASSOC. If it finds an entry 
with KEY as its CAR, PUTASSOC replaces the associated value with VALUE 
using RPLACD since the value is the CDR of the entry. Otherwise, it adds a new 
entry to the association list using (CONS KEY VALUE). If ALST is not a list, 
PUTASSOC generates an error with the message “ARG NOT LIST”. For exam- 
ple, 


«(PUTASSOC 'checkers 'men games) 
men 


«games 
((bridge . cards) (baccarat . cards) (chess . men) (craps . 
dice) (scrabble . letters) (checkers . men)) 


«(PUTASSOC 'chess 'men-and-board games) 
men-and-board 
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“games 

((bridge . cards) (baccarat . cards) (chess . men-and- 
board) (craps . dice) (scrabble . letters) (checkers . 
men) ) 


We might define PUTASSOC as follows: 


(DEFINEQ 
(putassoc (key value alst) 
(PROG (entry) 
(COND 

((NLISTP alst) 
(ERRORX '(4 T))) 

((SETQ entry (ASSOC key alst)) 
(RPLACD entry value) ) 

(T 
(NCONC alst (CONS key value) ) 
(RETURN value) )) ) 


)) 


6.10.3 Removing an Entry 


As we mentioned above, removing an entry from an association list may be con- 
sidered equivalent to setting the associated value of the key to NIL. Let us create 
a function DELASSOC that removes an entry from an association list. It takes 
the form 


Function: DELASSOC 

# Arguments: 2 

Arguments: 1) a search item, KEY 
2) an association list, ALST 

Value: An association list with the entry 
corresponding to KEY removed if it was 
present. 


We might define a function DELASSOC as follows: 


(DEFINEQ 
(delassoc (key alst) 
(PUTASSOC key NIL alst)) 
)) 
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However, this has the unfortunate side effect that, if an entry with KEY as 
its CAR is not found, then an entry of the form (CONS KEY NIL) will be added 
to the association list. If we are processing sparse association lists (where the 
domain of keys is large but the actual key instances are relatively small), the 
association list will grow with the addition of many entries of the form (<key) . 
NIL). This can have a deleterious effect on program performance since the entire 
association list must be searched each time. So, let us redefine DELASSOC as 
follows: 


(DEFINEQ 
(delassoc (key alst) 
(PROG (entry) 
(COND 
((NLISTP alst) 
(ERRORX (LIST 4 'T))) 
((SETQ entry (ASSOC key alst)) 
(RPLACD entry NIL) ) 
(T NIL))) 
)) 


This version is somewhat better in that it adds nothing to the association list 
if the KEY is not found. However, after some period of time, the list may be 
“‘littered’’ with entries of the form ({key) . NIL) as a result of setting previous 
associations to NIL. What we really intended to do, in many cases, was to re- 
move the entry entirely. The following definition shows how we can do either 
case: 


(DEFINEQ 
(delassoc (key alst dflag) 
(PROG (entry) 
(COND 
((NLISTP alst) 
(ERRORX (LIST 4 'T))) 
((SETQ entry (ASSOC key alst)) 
(COND 
(dflag 
(RPLACD entry NIL)) 
(T 
(DREMOVE entry alst)))))) 
)) 


where DFLAG determines whether we set the associated flag to NIL or remove 
the entry from the association list. If DFLAG is NIL, the entry will be removed. 
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6.10.4 Adding a Value to an Association List Entry 


Often, the value associated with a key in an association list will be a list itself. 
You may want to add a value to that list. Let us define a function ADDASSOC 
that performs this operation. It takes the form 


Function: ADDASSOC 
# Arguments: 3 


Arguments: 1) a search item, KEY 
2) a value to be added to an entry, VALUE 
3) an association list, ALST 


Value: An association list. 


ADDASSOC determines if an entry having KEY is present in the associa- 
tion list. If so, it adds VALUE to the value of the entry, converting it to a list if it 
is not already one. If no entry is present, ADDASSOC creates a new entry con- 
sisting of KEY and VALUE. 

We can define ADDASSOC which performs this operation: 


(DEFINEQ 
(addassoc (key value alst) 
(PROG (entry) 
(COND 
((NLISTP alst) 
(ERRORX (LIST 4 'T))) 
((SETQ entry (ASSOC key alst)) 
(RPLACD entry 
(APPEND (CDR entry) 
(COND 
((NLISTP value) 
(LIST value) ) 

(T value) )))) 

(T NIL) )) 


)) 


6.11 SEARCHING LISTS 


We have seen that we can search lists using MEMBER or ASSOC. MEMBER 
(Section 4.8) compares the key with each element in the list and returns the tail 
of the list. ASSOC (Section 6.10) compares the key with the CAR of an entry and 
returns the associated value. MEMBER works on lists whose elements are at- 
oms. ASSOC works on lists having the (<key) . (result)) format. In the next 
chapter, we shall see that certain functions also search the property lists of at- 
oms. 
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LISTGET and LISTPUT operate on the top-level values of atoms which are 
lists that have a property list format: 


(key[1] value[1] key[2] value[2] ... key[n] value[n]) 


6.11.1 Searching Lists in Property List Format 
LISTGET searches a list two elements at a time. It takes the form 


Function: LISTGET 
LISTGET1 


# Arguments: 2 


Arguments: 1) a list, LST 
2) a search key, KEY 


Value: The next value after the key. 


LISTGET searches LST using CDDR to access every other element, i.e., it 
assumes property list format. If an element is EQ to KEY, it returns the next 
element in the list. We might define it as: 


(DEFINEQ 
(listget (1st key) 
(COND 
((NLISTP 1st) 
(ERROR ''ARG NOT LIST'' 1st))) 
(PROG (alst entry) 
(SETQ alst (COPY lst)) 
loop 
( AND 
(EQ key (CAR alst)) 
(RETURN (CADR alst))) 
(SETQ alst (CDDR alst)) * 
(AND alst (GO loop)) 
(RETURN NIL) ) 


)) 


An alternative form, LISTGET1, searches the list one CDR at a time. Its 
definition differs from LISTGET only slightly in that we change the expression 
indicated by * above to 


(SETQ alst (CDR alst)) 
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6.11.2 Replacing Elements in Place in a List 


We may modify a list in place by searching for a value and replacing it. LIST- 
PUT acts like LISTGET but replaces the next element if the entry is found. It 
searches a list using CDDR just like LISTGET. It takes the form 


Function: LISTPUT 
LISTPUT1 


# Arguments: 3 


Arguments: 1). a@ list,. IST 
2) a search key, KEY 
3) a new value, VALUE 


Value: The new value. 
We might define LISTPUT as follows: 


(DEFINEQ 
(listput (lst key value) 
(COND 
((NLISTP 1st) 
(ERROR "not a list!'))) 
(PROG NIL 
loop 
(AND 
(EQ key (CAR lst)) 
(RPLACD (CAR lst) 
(APPEND (LIST value) 
(CDDR 1st) )) 
(RETURN value) ) 
(SETQ lst (CDDR lst)) * 
(AND lst (GO loop) ) 
(RETURN NIL) ) 


)) 


An alternative version, LISTPUT1, searches the list one CDR at a time. Its 
definition differs from LISTPUT only slightly in that we change the expression 
indicated by * above to 


(SETQ 1st (CDR 1st)) 
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So far, we have seen that atoms can have values. These values may be other 
atoms, such as numbers, or they may be lists. The value is retrieved by using the 
literal name of the atom in a function or just giving it to the top-level READ- 
EVAL-PRINT loop of INTERLISP. The problem with this approach is that an 
atom standing for some object may really have many characteristics. We want to 
be able to associate all those characteristics with the atom itself rather than 
building additional data structures in which we have to look up the name of the 
atom in order to find the value of the characteristic. 

INTERLISP provides us with a convenient method for storing the multiple 
attributes of an object with the atom which represents that object. This method 
is called the property list. A property list is a conventional list associated with an 
atom that is composed of pairs of values. Each pair consists of a property and a 
property value. Property names and property values are determined by the user. 
INTERLISP uses some predefined properties for internal functions associated 
with its utilities. 


7.1 CONCEPT OF THE PROPERTY LIST 


Suppose we are trying to construct an augmented transition network for natural 
language parsing. We need to describe each word in our “‘dictionary”’ by several 
attributes. We might require that each word have a class—a part of speech, a 
number—the person in which that word is used, and a tense—if it is a verb. For 
example, the word BOY has CLASS = noun and NUMBER = present tense, 
third person. 

We can define the following functions to define a word in the dictionary 


(DEFINEQ 
(define-word (a-word-definition) 
(MAPCAR (CDR a-word-definition) 
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(FUNCTION define-word-property) ) 
)) 


(DEFINEQ 
(define-word-property (a-property) 
(PUTPROP (CAR a-word-definition) 
(CAR a-property) 
(CDR a-property) ) 
)) 


To insert BOY into the dictionary, we execute the following function call 


(define-word 
' (boy 
(class noun) 
(number (1 3)))) 


This has the effect of placing the property CLASS on BOY’s property list 
with the value NOUN and the property NUMBER with the value (1 3). I deter- 
mined that the names of the properties would be CLASS and NUMBER. I also 
determined that the values of the properties would be NOUN and (1 3). Other 
values for CLASS might be VERB, ADJECTIVE, ADVERB, and so on. Other 
values for NUMBER might be (2 3), (3 3), and so on. 

The property list construct allows us to associate many values with a single 
atom. With BOY, which represents an object, we can associate many attributes 
that describe our knowledge about a boy. You are allowed to select the names of 
the properties and the types of their values. Be careful to distinguish between the 
value of an atom and the values associated with each of its properties. 

Properties would seem to be an efficient way of building a database to de- 
scribe an object, whether physical or conceptual. Early AI researchers at- 
tempted to use the notion of properties as a serious analogy to the attributes of 
real-world objects. However, they found that representing real-world object 
characteristics using properties was a difficult task because of the complexity 
required to model these objects to a sufficient degree of detail. Today, properties 
are used as a powerful representation mechanism that are used to build complex 
data structures that capture real-world object characteristics. 


7.1.1 The Uniqueness of Atoms 

Atoms are unique entities, but they have a scope in relation to how they are used. . 

Consider the following example: 
«(SETQ color 'black) 
black 


«-(PUTPROP 'color 'number 5) 
2 
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(PROG (color) 
(SETQ color 'red) 
(RETURN color) ) 
red 


“color 
black 


which shows that the atom COLOR used inside the PROG is a local variable 
whose existence lasts for the duration of the PROG. However, because it has the 
same name as an existing atom, INTERLISP saves its value (BLACK) prior to 
binding a new value inside the PROG expression. The mechanics of saving and 
restoring values for variables is discussed in Chapter 28. 


(PROG (color) 
(PUTPROP 'color 'number 10) 
(RETURN 
(GETPROP ‘color 'number))) 
10 


<-(GETPROP ‘color 'number) 
10 


Note, however, that changes to a property are not local to a PROG expres- 
sion or a function definition, even if the atom is a local variable. This is because 
each atom is a unique object. It may have different values bound to it throughout 
the execution of the program. The atom COLOR inside the PROG expression is 
the same atom that was bound at the top level (e.g., external to the PROG). 
Thus, changes to the property of the atom are global to the entire program be- 
cause it is exactly the same atom!. 


7.2 GETTING A PROPERTY 
To retrieve a property from the property list of an atom, you use the function 
GETPROP. GETPROP takes the following form: 

Function: GETPROP 

# Arguments: 2 


Arguments: 1) an atom, ATM 
2) a property name, PROPERTY 


Value: The value of the property if it exists on 
ATM's property list; otherwise NIL. 


If ATM is not an atom, GETPROP returns NIL. If the property is found on 
the property list of the atom, GETPROP returns the value associated with that 
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property name. If the atom does not have a property list or no property by that 
name exists on the property list, GETPROP returns NIL. Thus, it is not a good 
idea to choose NIL as the default value of a property because it is difficult to 
distinguish whether the property has been initialized or really has the value NIL. 

Suppose I want to retrieve the property CLASS of the word BOY from our 
dictionary. I would say 


«-(GETPROP 'boy 'class) 
noun 


Note that GETPROP returns the value associated with property which, in 
this case, is the atom NOUN. 
If I wished to retrieve the NUMBER of BOY, I would say 


<-(GETPROP 'boy 'number) 
(1 3) 


Note that GETPROP returns the exact value of the property. In one case, it 
was an atom while in the other it was a list. 
If I asked for the TENSE of BOY: 


<-(GETPROP 'boy 'tense) 
NIL 


because the word BOY does not have a tense since it is not a verb. 

Often, we will initialize the values of properties on a property list to NIL 
because we will set them later on in the course of the program. In this case, 
GETPROP will return the value NIL when we access that property. To distin- 
guish whether or not the property exists versus whether it exists with value NIL, 
we must use the following form [irm78]: 


(MEMBER property (GETPROPLIST atom) ) 
We might define GETPROP as follows: 


(DEFINEQ 
(getprop (atm property) 
(COND 
((LITATOM atm) 
(PROG (propist) 
(SETQ proplst (GETPROPLIST 
atm) ) 
loop 
(COND 
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((OR 
(NLISTP proplst) 
(NLISTP (CDR 
proplst) ) ) 
(RETURN NIL)) 
((EQUAL (CAR proplst) 
property) 
(* 


Extract value of 
property from the 
list. 


(RETURN (CADR 
proplst) ))) 
(SETQ proplst (CDDR proplst) ) 
(GO loop) )) 
(T NIL)) 
)) 


7.2.1 Getting the Entire Property List 


GETPROP is used for retrieving the value of a single property. Sometimes, I 
want to manipulate the entire property list of an atom. I can retrieve the entire 
property list by executing GETPROPLIST. GETPROPLIST takes the form 


Function: GETPROPLIST 

# Arguments: 1 

Argument: 1) an atom, ATM 

Value: A list, possibly NIL, representing the 


entire property list associated with ATM. 


If the argument is not an atom, GETPROPLIST generates an error: ARG 
NOT LITATOM. For example, 


<(SETQ word 'boy) 
boy 


«(GETPROPLIST word) 
((class noun) (number (1 3))) 


but 


<(SETQ word '(boy)) 
(boy) 
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-(GETPROPLIST word) 
ARG NOT LITATOM 


Here is a more complex example: 


«(PRINTDEF (GETPROPLIST 'DECLARE) ) 
(10MACRO (X (PROGN 
(MAPC X 
(FUNCTION 
(LAMBDA (X MACROX) 
(COND 
((NEQ (CAR X) 'CLISP:) 
(EVAL X)))))) 
(REFRAME) 
' INSTRUCTIONS) ) 
CLISPWORD (FORWARD . declare) ) 


which has two properties: 1OMACRO and CLISPWORD. The value of 
10MACRO is the macro definition for the atom DECLARE. 


7.3 PUTTING PROPERTIES 


The corresponding functions for putting properties are PUTPROP and SET- 
PROPLIST. PUTPROP takes the following form: 


Function: PUTPROP 
# Arguments: 3 


Arguments: 1) an atom, ATM 
2) a property name, PROPERTY 
3) a value, VALUE 


Value: The value of the property. 


PUTPROP puts the specified property on the property list of the atom with 
the given value. If the property already exists, the given value replaces the old 
value. If the first argument is not an atom, PUTPROP generates an error mes- 
sage, ARG NOT LITATOM. For example, 


<(PUTPROP 'maryland 'capitol 'annapolis) 
annapolis 


«-(GETPROPLIST 'maryland) 
(capitol annapolis) 


because the property CAPITOL did not previously exist. Now, by applying PUT- 
PROP again 
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«-(PUTPROP 'maryland 'capitol 'baltimore) 
(new CAPITOL property for MARYLAND) 
baltimore 


because we performed this operation at the top level of the READ-EVAL- 
PRINT loop. 


«-(GETPROPLIST 'maryland) 
(capitol baltimore) 


A Definition for PUTPROP 
We might define PUTPROP as follows: 


(DEFINEQ 
(putprop (atm property value) 
(COND 
((NULL atm) 
(* 


If ATM is null, generate an 
error. 


(ERRORX (LIST 7 (LIST atm 
property) ))) 
((NOT (LITATOM atm) ) 
(ERROR "ARG NOT LITATOM' atm) ) ) 
(PROG (proplst) 
(SETQ proplst (GETPROPLIST atm) ) 
loop 
(COND 
((NLISTP proplst xprop atemp) 
(COND 
( (AND 
(NULL prop1lst) 
xtemp) 
(* 
We have encountered 
the end of the 
property list where 
there are an even 
number of entries, 
i.e., one value for 
every property name. 


) 

(SETQ atemp 
(LIST property 
value) ) 
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(RPLACD (CDR xprop) atemp)) 
(RETURN value) ) ) 
(* 


Note: the property 
list was initially NIL 
or a non-list, so we 
add the new property 
at the beginning. 


)) 
((NLISTP (CDR proplst) ) 
(* 


The property list 
terminates at an odd 
position, e.g., a name 
followed by no value or a 
name with the value CONSed 
to it. So add it at the 
beginning. 


((EQ (CAR xprop) property) 
(* 
The property name is found 


in the property list, so 
just replace the value. 





(RPLACA (CDR xprop) value) 
(RETURN value) ) 


(SETQ xprop proplst) 
(SETQ proplst (CDDR xprop)) 
(GO loop) )) 
(* 
Add new property and value to front 
of property list. 


(SETQ atemp 
(CONS property 
(CONS value 
(GETPROPLIST atm)))) 
(SETPROPLIST atm atemp) 
(RETURN value) ) 
)) 


eS ~— 


7.3 Putting Properties 201 


7.3.1 Assigning Multiple Properties 


In many cases, you may wish to assign multiple properties to an atom. This can 
be a tedious operation if each assignment requires a single invocation of PUT- 
PROP. INTERLISP provides an alternative, PUTPROPS, to perform multiple 
property assignments. It takes the form 


Function: PUTPROPS 
# Arguments: 3-N 


Arguments: 1) an atom, ATM 
2) a property name, PROPERTY 
3) a value, VALUE 
4-N) property name/value pairs 


Value: NIL 


PUTPROPS is an NLAMBDA, nospread function. 

PUTPROPS takes successive pairs of property names and values and places 
them on the property list of the specified atom. Its value is NIL. Consider the 
following example: 


<(PUTPROPS maryland 
governor harry-hughes 
(senators (charles-mathias paul-sarbanes) 
counties (kent harford) ) 

NIL 


«-(GETPROPLIST 'maryland) 

(capitol annapolis governor harry-hughes senators 
(charles-mathias paul-sarbanes) counties 
(kent harford) ) 


Note that the arguments to PUTPROPS are not evaluated. Thus, you do not 
need to quote MARYLAND and any of the arguments. 


7.3.2 Setting the Property List 
You may also construct the property list yourself and then assign it to an atom 
via SETPROPLIST. SETPROPLIST takes the form 

Function: SETPROPLIST 

# Arguments: 2 


Arguments: 1) an atom, ATM 
2) an S-expression, EXPRESSION 
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Value: The property list which is the value of 
EXPRESSION. 


SETPROPLIST sets the property list of ATM to be the value of its second 
argument. If the first argument is not an atom, SETPROPLIST displays the 
error message ARG NOT LITATOM. If the first argument is NIL, SETPRO- 
PLIST displays the error message ATTEMPT TO RPLAC NIL. However, if the 
S-expression is also NIL, SETPROPLIST merely returns NIL. For example, 


«-(SETPROPLIST 'maryland 
(LIST 'governor 'hughes 
'senators (LIST 'mathias 
'sarbanes) ) ) 
(governor hughes senators (mathias sarbanes) ) 


«-(GETPROPLIST 'maryland) 
(governor hughes senators (mathias sarbanes) ) 


Note that any property list that previously existed for MARYLAND is com- 
pletely replaced by SETPROPLIST. 





7.3.3 Defining a Property for Multiple Atoms 


You may wish to assign the same property to many atoms with the same or dif- 
ferent values. DEFLIST takes the form 


Function: DEFLIST 

# Arguments: 2 

Arguments: 1) a list of atom-value pairs, LST 
2) a property name, PROPERTY 

Value: NIL 


LST is a list of elements each of which has the form 
(<atom) . <value)) 


DEFLIST puts PROPERTY on the property list of every atom which is the 
CAR of an entry on LST with the value which is the CDR of that entry. Consider 
the following example: 


«-(DEFLIST '((maryland hughes) 
(virginia robb) 
(massachusetts dukakis) 
(texas white) ) 

'governor) 
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NIL 


*-(GETPROPLIST 'maryland) 
(capitol annapolis governor hughes) 


«-(GETPROPLIST 'texas) 
(governor white) 


A Definition for DEFLIST 
We might define DEFLIST as follows: 


(DEFINEQ 
(deflist (lst property) 
(PROG NIL 
loop 
(COND 
((NLISTP lst) 
(RETURN NIL) )) 
(PUTPROP (CAAR lst) 
property 
(CADAR lst) ) 
(SETQ lst (CDR lst)) 
(GO loop) ) 
)) 


7.4 MODIFYING PROPERTY LISTS 
INTERLISP provides three functions for modifying property lists: 


ADDPROP adds a new property 
REMPROP removes a property 
CHANGEPROP changes the name, but not the value, of a property 


7.4.1 Adding a Property 


A property may have a list (or other data structure) as its value. Adding a new 
value to that list usually requires the creation of a new list structure with the 
value added to the front or back of the list. For example, 


«(SETQ property-value (GETPROP atm prop) ) 
«(PUTPROP atm prop (CONS property-value newvalue) ) 


or 


(PUTPROP atm prop (APPEND property-value newvalue) ) 
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To avoid creating a new list structure, INTERLISP provides ADDPROP to 
add a value to a list which is the value of the property. It takes the form 


Function: ADDPROP 
# Arguments: 4 


Arguments: 1) an atom, ATM 
2) a property name, PROPERTY 
3) a new value, NEW 
4) a flag, FLAG 


Value: The value of the new property. 


FLAG controls the terminus at which the property will be added. If FLAG is 
T, the new property is CONSed to the front of the list; otherwise, it is NCONCed 
to the end of it. If no property exists for the atom, the effect is the same as 


(PUTPROP atm prop (LIST new)) 
For example, 


«-(ADDPROP 'maryland 'representatives 'byron) 
(byron) 


«<-(GETPROP 'maryland 'representatives) 
(byron) 


«<-(ADDPROP 'maryland 'representatives 'barnes T) 
(barnes byron) 


«-(GETPROP 'maryland 'representatives) 
(barnes byron) 


<(ADDPROP 'maryland 'representatives 'hoyer) 
(barnes byron hoyer) 


«-(GETPROP 'maryland 'representatives) 
(barnes byron hoyer) 


A Definition for ADDPROP 
We might define ADDPROP as follows: 


(DEFINEQ 
(addprop (atm property value flag) 
(COND 
((NULL atm) 
(ERROR "ATTEMPT TO RPLAC NIL")) - 
((NOT (LITATOM atm)) 
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(ERROR "ARG NOT LITATOM'' atm) ) ) 
(PROG (x proplst) 
(SETQ x atm) 
loop 
(COND 
((NLISTP (CDR x)) 
(* 


Note that the CDR cell of an 
atom contains the pointer to the 
property list form that atom. 


Here, we have reached the end of 
the property list, so we just 
RPLACD a new entry onto its end. 
) 
(SETQ proplst 
(LIST property 
(SETQ value 
(LIST value) ))) 
(RPLACD x proplst) ) 
((EQ (CADR x) property) 
(* 


Found the property name in the 
property list. 


(RPLACA (CDDR x) 
(SETQ value 
(COND 
(flag 
(CONS value 
, (CADDR x))) 
T 
(NCONC1 (CADDR x) 
i value) ))) 
((SETQ x (CDDR x)) 
(* 


Have not found property; 


advance along property 
list. 


) 
(GO loop) ) 


(* 


(T 


Property list ended on a 
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property name with no 
value. 


(SETQ proplst 
(CONS property 
(CONS 
(SETQ value 
‘ (LIST value) ) 

(CDR atm)))) 

(RPLACD atm proplst) )) 

(RETURN value) ) 
)) 


7.4.2 Removing a Property 


You may remove a property from the property list via REMPROP. It takes the 
form . 


Function: REMPROP 
# Arguments: 2 


Arguments: 1) an atom, ATM 
2) a property name, PROPERTY 


Value: The property name or NIL. 


REMPROP removes all occurrences of the specified property and its value 
from the atom’s property list. If any occurrences are found, its value is the name 
of the property. Otherwise, it returns NIL. Note that multiple occurrences of a 
property may appear in a property list if the list was assigned to the atom via 
SETPROPLIST. Consider the following examples: 


«<-(GETPROPLIST 'maryland) 
(capitol annapolis governor hughes senators 
(mathias sarbanes) counties (kent harford) ) 


«(REMPROP 'maryland ' governor) 
governor 


«-(GETPROPLIST 'maryland) 
(capitol annapolis senators (mathias sarbanes) counties 
(kent harford) ) 


«-(REMPROP 'maryland 'population) 
NIL 
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A Definition for REMPROP 
We might define REMPROP as follows: 


(DEFINEQ 
(remprop (atm property) 
(COND 
((NULL (LITATOM atm) ) 

(ERROR "ARG NOT LITATOM' atm) )) 

(PROG (proplst newproplst value) 
(SETQ proplst 

(GETPROPLIST atm) ) 

loop 
(COND 
((OR 

(NLISTP proplst) 

(NLISTP (CDR proplst) )) 

(RETURN value) ) 

((EQUAL (CAR proplst) property) 
(SETQ value property) 
(COND 
(newproplst 
(RPLACD (CDR newproplst) 
(CCDR proplst) ) ) 
(T 
(SETPROPLIST atm 
(CDDR newprop1st) ) ) 


)) 
(T 
(SETQ proplst 
(CDDR (SETQ newproplst proplst))))) 
(GO loop) ) 
)) 


7.4.3 Removing the Property List 
To remove multiple properties, INTERLISP provides the function REMPRO- 
PLIST. It takes the form 

Function: REMPROPLIST 

# Arguments: 2 


Arguments: 1) an atom, ATM 
2) a list of property names, PROPLST 


Value: NIL 
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REMPROPLIST removes all the properties whose names appear in PRO- 
PLST from the property list of the specified atom. 

To remove the entire property list of an atom, you may use one of the follow- 
ing function calls: 


(SETPROPLIST (atom) NIL) 
(REMPROPLIST <atom) (PROPNAMES <atom))) 


Note: Many atoms in INTERLISP already have property lists with proper- 
ties used by various system packages. You should be careful not to delete such 
properties as they may cause the system to malfunction (or cease to function). 
You may use SYSPROPS to obtain a list of all the system property names. 

Heeding this advice, we should rewrite the second expression above as fol- 
lows 


(MAPC (PROPNAMES <atom)) 
'(LAMBDA (name) 
(COND 
((MEMBER name (SYSPROPS)) NIL) 
(T (REMPROP <atom) name))))) 


Consider the following example where we force the property list to have mul- 
tiple copies of a property name 


«-(SETPROPLIST x '(abcdabefghab)) 
(abedabefghab) 


The property name A is repeated three times in this property list. Now, we 
may remove A via REMPROPLIST 


«-(REMPROPLIST 'x '(A)) 
NIL 


«-(GETPROPLIST 'x) 
(ec de f gh) 


7.4.4 Changing Property Names 


The foregoing functions changed the structure of the property list by adding or 
deleting a property and its associated value. Sometimes, you want to keep the 
value but change the name of the property. CHANGEPROP takes the form 


Function: CHANGEPROP 
# Arguments: 3 
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Arguments: 1) an atom, ATM 
2) a property name, PROPERTY1 
3) a property name, PROPERTY2 


Value: The atom name. 


CHANGEPROP changes the name of property PROPERTY1 to the name 
given by PROPERTY? on the property list of ATM. If PROPERTY1 does not 
exist on ATM’s property list, it returns NIL. If ATM is not a literal atom, 
CHANGEPROP generates an error with the message “ARG NOT LITATOM”. 

Consider the following example: 


<(GETPROPLIST 'maryland) 
(capitol annapolis governor hughes senators (mathias 
sarbanes) ) 


Note that we have used the property name SENATORS to represent the 
United States senators. However, Maryland has a bicameral legislature in which 
the upper house is also called the Senate. So, let us rename the property SENA- 
TORS to US-SENATORS to avoid confusion. 


<-(CHANGEPROP 'maryland 'senators 'us-senators) 
maryland 


<-(GETPROPLIST 'maryland) 
(capitol annapolis governor hughes us-senators (mathias 
sarbanes) ) 


A Definition for CHANGEPROP 
We might define CHANGEPROP as follows: 


(DEFINEQ 
(changeprop (atm property1 property2) 
(COND 
((NOT (LITATOM atm) ) 
(ERRORX (LIST "ARG NOT LITATOM"' 
atm) ) ) 
((SETQ property1 
(MEMBER property1 (GETPROPLIST 
atm) ) ) 
(* 
Only change the name if 
property1 is actually present in 
the property list. 
) 
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(RPLACA property1 property2) 
atm) ) 


)) 


7.5 OBTAINING THE PROPERTY NAMES OF AN ATOM 


PROPNAMES allows you to obtain a list of the property names associated with 
an atom. It takes the form 


Function: PROPNAMES 

# Arguments: 1 

Arguments: 1) an atom, ATM 

Value: A list of the property names. 


PROPNAMES is useful when you want to apply a function to all the proper- 
ties of an atom. For example, to delete all of the properties associated with an 
atom, we can use the following expression: 


(REMPROPLIST atm (PROPNAMES atm) ) 


We might print the properties and their associated values using the follow- 
ing expression 


(MAPC (PROPNAMES atm) 
"(LAMBDA (name) 
(PRIN1 name) 
(SPACES 2) 
(PRINTDEF (GETPROP atm name) ))) 


A Definition for PROPNAMES 
We might define PROPNAMES as follows: 


(DEFINEQ 
(propnames (atm) 
(PROG (propnamelst prop1st) 
(SETQ proplst (GETPROPLIST atm) ) 
(SETQ propnamelst NIL) 
loop 
(COND 
((NLISTP proplst) 
(RETURN propnamelst) ) ) 
(SETQ propnamelst 
(APPEND propnamelst (CAR proplst) )) 
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(SETQ proplst (CDDR proplst)) 
5 (GO loop) ) 


7.5.1 Obtaining the System Property Names 


INTERLISP has many predefined property names that are used by various sys- 
tem packages. You may obtain a list of the system property names by executing 
SYSPROPS which takes the form 


Function: SYSPROPS 

# Arguments: 0 

Arguments: NIL 

Value: A list of system property names. 


For example, the following list was obtained by executing SYSPROPS un- 
der the Fugue release on a Xerox 1100 Scientific Information Processor: 


+ (SYSPROPS) 

(BYTEMACRO ALTOMACRO JMACRO VAXMACRO DMACRO 10MACRO 
VARTYPE HASDEF FILEPKGCONTENTS PROPTYPE ALISTTYPE DELDEF 
EDITDEF PUTDEF GETDEF WHENCHANGED NOTICEFN NEWCOMFN 
PRETTYTYPE DELFROMPRETTYCOM ADDTOPRETTYCOM ACCESSFN ACS 
ADVICE ADVISED ALIAS AMAC ARGNAMES BLKLIBRARYDEF BRKINFO 
BROADSCOPE BROKEN BROKEN-IN CLISPCLASS CLISPCLASSDEF 
CLISPFORM CLISPIFYISPROP CLISPINFIX CLISPISFORM 
CLISPISPROP CLISPNEG CLISPTYPE CLISPWORD CLMAPS CODE 
CONVERT COREVAL CROPS CTYPE EDIT-SAVE EXPR FILE 
FILECHANGES FILEDATES FILEDEF FILEGROUP FILEHISTORY 
FILEMAP FILETYPE GLOBALVAR HISTORY I.S.OPR 1.S.TYPE INFO 
LASTVALUE LISPFN MACRO MAKE NAMESCHANGED NARGS OLDVALUE 
OPD READVICE SETFN SUBR UBOX UNARYOP VALUE DEF 
CLISPBRACKET ) 


7.6 EXTRACTING A PROPERTY SUBLIST 


You may extract a sublist of the property list using GETLIS, which takes the 
form 


Function: GETLIS 
# Arguments: 2 
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Arguments: 1) an atom, ATM 
2) a list of properties, PROPLST 
Value: The tail of the property list for ATM. 


GETLIS searches the property list of ATM using the values found on PRO- 
PLST which may be an atom or a list of properties. It returns the tail of the 
property list beginning with PROPLST. If PROPLST is an atom, then that 
property name is the CAR of the result. If PROPLST is a list, GETLIS uses each 
element on PROPLST as a search key until one matches a property of ATM. The 
tail of the property list beginning with that element is returned. 

If no element of PROPLST is found on the property list of ATM, GETLIS 
returns NIL. For example, 


«-(GETLIS 'maryland '(us-senators) ) 
(us-senators (mathias sarbanes) counties (kent harford) ) 


«(GETLIS 'maryland 'governor) 
NIL 


«(GETLIS 'maryland 'capitol) 
NIL 


Note that if PROPLST is an atom, as in the case above, GETLIS returns 
NIL. Thus, you cannot determine whether or not the property exists. 


A Definition for GETLIS 
We might define GETLIS as follows: 


(DEFINEQ 
(getlis (atm proplst) 
(PROG (atmproplst) 
(SETQ atmproplst (GETPROPLIST atm) ) 
loop 
(COND 
((OR 
(NLISTP atmproplst) 
(MEMBER (CAR atmproplst) 
proplst) ) 
(RETURN atmprop1st) ) ) 
(SETQ atmproplst (CDR atmprop1st) ) 
(GO loop) ) 


)) 


Note that GETLIS makes no distinction between the property names and 
their values when it searches the atom’s property list. 
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Function Definition 
and Evaluation 


INTERLISP embodies the mathematical definition of a function as a procedure 
or specification for action. A function takes zero or more arguments as inputs 
and produces one or more values as outputs. Unlike mathematical functions, 
however, INTERLISP functions exist within a program—a collection of func- 
tions gathered to accomplish a purpose—and, so, may have side effects on 
global variables defined within the program. 

In INTERLISP, there are three ways to create a function for evaluation: 


1. Use DEFINEQ or PUTD to attach the definition to an atomic symbol 
(Section 8.2.2) 

2. Place the definition on an atom’s property list under one of the properties 
EXPR, FEXPR, or MACRO (Section 7.3) 

3. Dynamically bind a definition to an atom through the FUNARG mecha- 
nism (Section 12.4) 


Because atoms have both value cells and function definition cells, we cannot 
determine whether an arbitrary data object is to be used as a variable or a func- 
tion. Usage is determined by how the data object is evaluated (e.g., which primi- 
tive functions are applied to it) because the value cell and the function definition 
cell may both have non-NIL values. 

The primary focus of this chapter is to discuss the definition and evaluation 
of user-defined functions. Several system functions allow you to obtain informa- 
tion about a function and its arguments. Most functions do not retain any histor- 
ical information about previous invocations unless you explicitly build their 
structures to do so. Generators are a simple mechanism for maintaining status 
information across function invocations. 


8.1 FUNCTION TYPES 
INTERLISP provides two types of functions: EXPRs and SUBRs. 
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An EXPR is a function that is written in INTERLISP; it is interpreted. Each 
literal atom has a function definition cell in which a function definition may be 
stored. A function definition is a pointer to a list that describes the procedure 
that the function performs. Note that the atom may also have a defined value 
that is independent of its function definition. 

A SUBR is a function that is hand-coded in machine language (IN- 
TERLISP/370) or is provided by the underlying virtual machine firmware (IN- 
TERLISP-D). Compiled functions (see below) are treated as SUBRs. 

The distinction is important because the functions PUTD and GETD oper- 
ate differently upon the two types of functions. You cannot define a SUBR with 
either DEFINE or DEFINEQ. When you compile an EXPR function, you effec- 
tively convert it to a SUBR when it is loaded into memory. 

Applying GETD to an EXPR function name returns the list comprising the 
function definition. Applying GETD to a SUBR returns a dotted pair that has 
the following characteristics: 


The CAR of the dotted pair is an encoded form of 


1. the argument type 
2. the number of arguments 


The CDR of the dotted pair is the address of the first instruction of the 
function. 


INTERLISP allows us to modify the basic concept of a function in two re- 
spects: whether or not the arguments are evaluated, and whether or not the func- 
tion has a definite number of arguments. 


8.1.1 To Evaluate or Not 


Normally, arguments passed to functions are evaluated to yield their respective 
values which are then used by the function. This is called a LAMBDA-type func- 
tion. Consider the following example: 


«(SETQ integer-1 10) 


10 

«(SETQ integer-2 20) 

20 

«-(IDIFFERENCE integer-1 integer-2) 
-10 


IDIFFERENCE is a LAMBDA-type function. The values that IDIF- 
FERENCE receives are the numbers 10 and 20 which are the values of the argu- 
ments when they are evaluated. This mechanism is known as call by value in 
other languages. 
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You may specify that a function’s arguments not be evaluated when the 
function is invoked. This is known as an NLAMBDA-type function and the 
mechanism is similar to a call by reference in other languages. DEFINEQ (see 
below) is an NLAMBDA-type function. Consider the following example: 


(DEFINEQ 
(exchange (pair) 
. (LIST (CADR pair) (CAR pair)) 


The argument to DEFINEQ is not evaluated but is passed to DEFINEQ for 
internal evaluation. Thus, the value passed to DEFINEQ is the list 


(exchange (pair) (LIST (CADR pair) (CAR pair))) 


When FNTYP (see Section 8.1.5) is applied to NULAMBDA-type functions, 
it returns the type of the function prefixed by the letter F: FEXPR or FSUBR. 


8.1.2 To Spread or Not 


Normally, a function is defined with a definite number of arguments that are 
enumerated in its parameter list. INTERLISP matches the arguments specified 
in the function invocation with the parameters specified by the function defini- 
tion (i.e., we say the arguments are spread across the parameters). If there are 
not enough arguments to satisfy all the parameters, INTERLISP substitutes 
NIL for the remaining parameters. If there are more arguments than parame- 
ters, the excess arguments are ignored (but there are a few exceptions, e.g., see 
QUOTE). 

Sometimes, we want to pass an indefinite number of arguments to a func- 
tion. The number and type of arguments may be dependent on the arguments 
themselves. How the arguments are to be evaluated is determined within the 
function itself. This is called a nospread function. 

To define a nospread function, we give a single variable, not enclosed in 
parentheses, after the LAMBDA or NLAMBDA declaration. For example, 


(DEFINEQ 
(add 
(LAMBDA x 
(PROG (sum lst) 
(SETQ sum 0) 
(SETQ lst (copy x)) 
(AND (NULL 1st)(RETURN sum) ) 
loop 
(SETQ sum (plus sum (car x))) 
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(AND 
(SETQ lst (CDR lst)) 
(GO loop) ) 
(RETURN sum) ) 
))) 


where X is a list of all the arguments presented in the calling sequence to the 
function. The arguments are evaluated or not depending on whether the func- 
tion is defined to be LAMBDA or NLAMBDA. For example, 


«(ADD 10 20 30) 


would set X to the list (10 20 30). 

When FNTYP is given the name of a function which does not spread its 
arguments, it returns the type of the function with an asterisk (*) appended to 
the type name. 


8.1.3 Compiled Functions 


Most INTERLISP functions are interpreted. Even in the best of circumstances, 
interpretation can be a lengthy process. Once a function is debugged and ready 
for production use, you may compile the function. INTERLISP provides a com- 
piler (see Chapter 31) that converts the INTERLISP source code into the under- 
lying computer’s machine language. When FNTYP is given the name of a func- 
tion that has been compiled, it returns the type of the function preceded by the 
letter C: CEXPR or CFEXPR. For the purposes of applying GETD to compiled 
functions, they are treated like SUBRs. 


8.1.4 Summary of Function Types 


In summary, there are 12 types of functions supported by INTERLISP. These 
are shown in the following table: 


EXPR SUBR 
EXPR SUBR 
EXPR* SUBR* 
FEXPR FSUBR 
FEXPR* FSUBR* 
CEXPR 

CEXPR* 

CFEXPR 

CFEXPR* 


Note that SUBRs, because they are written in machine language, already 
exist in a compiled state. : 
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8.1.5 Determining the Function Type 


You may determine the type of a function by executing FNTYP. FNTYP takes 
the following form 


Function: FNTYP 

# Arguments: 1 

Argument: 1) a function name, FN 
Value: The function type. 


The argument of FNTYP may be either the name of a defined function or a 
function definition itself. The value of FNTYP is an atom taken from the table 
below. Otherwise, it returns NIL. For example, 


«-(FNTYP 'GETD) 
CEXPR 


«-(FNTYP 'DEFINE) 
CEXPR 


<(FNTYP 'DEFINEQ) 
CFEXPR* 


<(FNTYP '(LAMBDA (pair) 
(LIST (CADR pair) (CAR pair) ))) 
EXPR 


where FNTYP has checked the function definition (indicated by the LAMBDA) 
to determine the function type. 


«<(SETQ a-function 'GETD) 


<(FNTYP a-function) 
CEXPR 


FNTYP may also return the atom FUNARG if the argument is a function 


argument expression (see Section 12.4). 
The value of FNTYP is one of the following twelve literal atoms, based on 


the type of the function: 


Expressions Compiled Built-In 
Lambda-Spread EXPR CEXPR SUBR 
Nlambda-Spread FEXPR CFEXPR FSUBR 
Lambda-Nospread EXPR* CEXPR* SUBR* 


Nlambda-Nospread FEXPR* CFEXPR* FSUBR* 
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The types in the Built-In column are returned only for INTERLISP-10 and 
INTERLISP/370. 


A Definition for FNTYP 
We might define FNTYP as follows (after INTERLISP/370): 
(DEFINEQ 
(fntyp (fn) 
(SELECTQ (NTYP (MKFNIND fn)) 
((0 4) 'FSUBR*) 
((1 5) 'FSUBR) 
((2 6) 'SUBR*) 
((3 7) 'SUBR) 
(8 ' FEXPR* ) 
(9 'FEXPR) 
(10 'EXPR* ) 
(11 'EXPR) 
(12 'CFEXPR*) 
(13 'CFEXPR) 
(14. 'CEXPR¥) 
(15 'CEXPR) 
(20 'FUNARG) 
NIL) 
)) 


where the number is an indication of the datatype for the atom. 


8.2 DEFINING FUNCTIONS 


You may define a new function in INTERLISP using either DEFINE or DE- 
FINEQ. Let us discuss DEFINEQ first and, then, explore the generalized ver- 
sion represented by DEFINE. 


8.2.1 Syntax of a Function Definition 


A function definition consists of the following components: 


The name of the function 

A declaration of function type: LAMBDA or NLAMBDA 
A parameter list or NIL 

The body of the function 


These items are combined together in a list which is passed to either DE- 
FINE or DEFINEQ. 
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The name of the function must be a symbolic atom that conforms to the 
naming conventions of the particular INTERLISP system that you are using. 

LAMBDA or NLAMBDA determines whether the function’s arguments are 
evaluated or not when the function is invoked. 

The parameter list is a list of the names of symbolic atoms, usually enclosed 
in parentheses, that represent the arguments to the function. Each symbolic 
atom may appear in the body of the function in which case we say that the atom 
is local to the function. The parameter list may be represented by the atom NIL 
which means that the function expects no arguments. The parameter list may 
consist of a single atom which indicates that the arguments are not spread. In 
this case, when the function is invoked, all arguments specified in the argument 
list are gathered into a list which is bound to the single atom. 

The body of the function is a sequence of INTERLISP statements that speci- 
fies the procedure of the function. Variables appearing in the function body that 
do not appear in the parameter list are assumed to be global variables for this 
function, although they may be local and bound in a function which invoked this 
function. When the function is executed, if the value of these variables is 
changed, we say that the function has a side effect. That is, the value of the 
variable persists beyond the execution of the function because the variable is 
defined outside the function. The value a function gives back when it is executed 
is called the value returned. This value is the result of the last statement executed 
within the function body, which may not necessarily be the last physical expres- 
sion in the function body. 


8.2.2 Defining a Function: DEFINEQ 


DEFINEQ is used to define one or more functions. It takes the form 


Function: DEFINEQ 
# Arguments: 1-N 
Arguments: 1) a list of one or more function forms, 
FNS 
Value: The names of the function that are 
defined. 


DEFINEQ is an NLAMBDA, nospread function. It takes an indefinite 
number of arguments that are not evaluated. Each entry in FNS must take the 
form required by DEFINE (see below). If it does not, DEFINEQ (or DEFINE) 
issues an error message “INCORRECT DEFINING FORM”. The File Package 
writes functions to symbolic files using DEFINEQ so that, when read in via 
LOAD, they will be defined anew in your virtual memory. 

DEFINEQ calls DEFINE with individual entries from FNS. 
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8.2.3 Defining a Function: DEFINE 


DEFINE is the LAMBDA-spread version for defining a function. It takes the 
form 


Function: DEFINE 

# Arguments: 1 

Arguments: 1) a list of lists, X 

Value: The names of functions defined as 


described in X. 





Each element of the list X is itself a list which takes one of two forms: 
1. (name) <definition)) 

where (definition) has the structure 

(<lambda-declaration) (arguments) <body)) 


A <lambda-declaration) is either a LAMBDA or an NLAMBDA. 
Functions written by the File Package to symbolic files take this form. 
Consider the example 


(DEFINEQ ; 
(CUBIC 
(LAMBDA (X) 
(ITIMES X (ITIMES X X)) 
))) 


2. ({name) (arguments) <body)) 


The function type is assumed to be LAMBDA. Most functions defined 
by type-in take this form. Consider the example 


(DEFINEQ 
(CUBIC (X) 
(ITIMES X (ITIMES X X)) 
)) 


The appropriate LAMBDA expression is automatically created by DE- 
FINEQ as the function definition is read. Thus, when you print the definition of 
CUBIC after typing it in, you will see a LAMBDA expression inserted into the 
definition. 
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The (name) field causes an atom to be created or updated with a function 
definition using a LAMBDA or NLAMBDA expression. The function definition 
is placed in the atom’s function definition cell. (arguments) is either NIL or a 
list of atoms representing arguments to be used by the function. The <body) is 
one or more S-expressions that are inspected for proper form (see below) and 
comprise the specification of the function. 

DEFINEQ works even if the function is broken, advised, or broken-in (see 
Chapters 20 and 21). 

If time stamping is enabled (see Section 29.6.2), DEFINEQ and DEFINE 
stamp the definition with a comment consisting of your initials and the date 
when the function was defined. 


8.2.4 The Effect of DFNFLG 
DFNFLG determines how DEFINE treats the proposed definition: 


DFNFLG is NIL 
If DFNFLG is NIL and <name) already has a definition, DEFINE displays the 
message ((name) REDEFINED). It saves the old definition, via SAVEDEF (see 
Section 17.5.7), on (name)’s property list before redefining it. 

Consider the following example: 


<DFNFLG 
NIL 


«(DEFINEQ (CUBIC (X) (ITIMES X (ITIMES X X)))) 
(CUBIC) 


<(DEFINEQ (CUBIC (X) (EXPT X 3))) 
(CUBIC redefined) 
(CUBIC) 


«-(GETPROP 'CUBIC 'EXPR) 
(EXPR (LAMBDA (X) (* edited: '11-June-84 20:06") 
(ITIMES X (ITIMES X X)))) 


DFNFLG is T 

If DFNELG is T, the function is simply redefined without the warning message. 
Consider the following example if it was executed after the second expres- 

sion in case 1: 


<-(SETQ DFNFLG T) 
T 


<(DEFINEQ (CUBIC (X) (EXPT X 3))) 
(CUBIC) 
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DFNFLG is PROP 
If DFNFLG is PROP or ALLPROP, the new definition is stored on (name)’s 
property list under the property EXPR. However, it does not place any definition 
in the atom’s function definition cell. Thus, attempting to get the definition of 
the function using GETD will return NIL. However, PP will work because it 
inspects both the function definition cell and the property list of the atom for a 
property named EXPR. 

DFNFLG initially has the value NIL. It is reset by LOAD (see Section 
17.9.1) when you load functions and variables from a file. 


8.2.5 Alternative Defining Forms 


INTERLISP/370 provides two alternative forms for defining functions: DE and 
DF. DE and DF define LAMBDA and NLAMBDA functions, respectively, in 
half-spread format. They take the following form 


Function: DE 
DF 


# Arguments: 3-N 


Arguments: 1) a function name, FN 
2) an argument list, ARGLST 
3-N) one or more S-expressions composing 
the body of the function, EXPRS 


Value: The function name, if successful. 
For example, we might define the function DISJOINT as 


(DE disjoint (la 1b) 
(COND ' 
((NULL la) T) 
((MEMBER (CAR la) 1b) NIL) 
XY 


(disjoint (CDR la) 1b)))) 


Basically, these functions provide a shorthand notation for defining func- 
tions that allow you to eliminate a few of the parentheses required by DEFINEQ. 
They have a form similar to DEFUN which is the defining function for the 
MACLISP family. 


A Definition for DE 
We might define DE as follows: 


(DEFINEQ 
(de (NLAMBDA (x . y) 
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(DEFINE 
(LIST 
(LIST x 
‘3 (CONS 'LAMBDA y)))) 


DF merely replaces the ‘LAMBDA in the CONS expression by ‘NLAMBDA 
to achieve the same effect. 


8.3 RETRIEVING A FUNCTION DEFINITION 


You may retrieve the definition of a function from its function definition cell by 
invoking GETD. GETD takes the format 


Function: GETD 

# Arguments: 1 

Argument: 1) the name of a function, FN 
Value: The definition of the function. 


GETD returns the definition of a function if it exists; otherwise, NIL. For 
example, 


(DEFINEQ 
(exchange (pair) 
(LIST (CADR pair) (CAR pair) ) 
)) 


<-(GETD 'exchange) 
(LAMBDA (PAIR) (LIST (CADR pair) (CAR pair))) 


If the function is compiled or a SUBR, GETD returns an encoded form 
representing the address of the first instruction of the function. For example 
(under the Fugue release of INTERLISP-D), 


«-(GETD 'getd) 
{ (CCODEP) }#1, 161244 


which is the encoded form of the dotted pair. CCODEP means that GETD is a 
compiled code pointer. #1 means that it takes one argument. 161244 is the mem- 
ory address where the first executable instruction of that procedure is located. 

Executing the same function under INTERLISP-10 returns the following 


form 


«-(GETD 'GETD) 
(1 . {STACK }#11271) 


224 Function Definition and Evaluation 


which reflects the different memory allocation models used in the two implemen- 
tations. Note that INTERLISP-10 returns the CONS of the function type with 
the address of the function. 

Note that INTERLISP returns a pointer to the function. Two successive 
calls to GETD will return two different pointers. These pointers are not EQ. 
Rather, EQUAL or EQP must be used to compare them. 


8.4 SETTING A FUNCTION DEFINITION 


We have seen, in Section 8.2, that we can define a function using either DEFINE 

or DEFINEQ. The effect of these functions is to place the given definition in the 

function definition cell of the symbolic atom that was specified as the name of 

the function. INTERLISP provides another mechanism for inserting values into 

an atom’s function definition cell. This is the function PUTD and its variations. 
PUTD takes the form 


Function: PUTD 
PUTDQ 
PUTDQ? 
# Arguments: 2 
Arguments: 1) the name of a function, FN 
2) a definition for the function, 
DEFINITION 
Value: The value of DEFINITION. 


The first argument must be a literal atom; otherwise, PUTD generates an 
error message: ARG NOT LITATOM. If the second argument is not a list, 
PUTD generates an error message: ILLEGAL ARG. NIL is a valid value for the 
second argument. Unlike DEFINE or DEFINEQ, PUTD does not check the list 
to see if it is a valid definition, but merely stores it away. For example, 


<(PUTD 'f-to-c 
"(LAMBDA (temperature) 
(QUOTIENT 
(DIFFERENCE temperature 32.0) 
1.8)))) 
(F-TO-C) 


which defines the atom F-TO-C as a function that converts a temperature given 
in fahrenheit to an equivalent measure in celsius. Note that the definition of the 
function given to PUTD must include either a LAMBDA or NLAMBDA. 

Note that PUTD is not sensitive to the value of DFNFLG, but places the 
value of DEFINITION directly in the function definition cell. Any contents of 
the function definition cell are replaced by the new definition. ; 
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8.4.1 Alternative Forms of PUTD 


An alternative form of PUTD is PUTDQ. PUTDQ is an NLAMBDA version of 
PUTD that assumes that both of its arguments are literal values. Thus, we may 
define F-TO-C as follows: 


«(PUTDQ f-to-c 
(LAMBDA (temperature) 
(QUOTIENT 
(DIFFERENCE temperature 32.0) 


1.8)))) 
(F-TO-C) 


Another form of PUTD is PUTDQ?. PUTDQ? is an NLAMBDA form of 
PUTD that sets the value of the function definition cell of the first argument if 
and only if it is not defined. That is, it acts like PUTDQ. Otherwise, it returns 
NIL and does nothing. 


A Definition for PUTDQ? 
We might define PUTDQ? as follows: 


(DEFINEQ 
(putdq? 
(NLAMBDA (fn definition) 
(AND (NULL (GETD fn)) 
(PUTD fn definition) ) 
))) 


8.5 COPYING FUNCTION DEFINITIONS 


Because function definitions are just lists or pointers to sequences of compiled 
code, we can copy a function definition from one atom to another. There are two 
reasons why you might want to perform this operation. 

First, to simplify the definition of several similar functions. In this case, you 
define a (perhaps lengthy) function. Then, you copy its definition to another 
atom and edit the definition to produce a similar but different function. 

Second, you may want to dynamically assign a function definition to an 
atom based on the current state of your program. 

INTERLISP provides MOVD to copy function definitions between atoms. 
An alternative form, MOVD?, copies the function definition to the destination 
atom if and only if its function definition cell is NIL; otherwise, it does nothing. 

The generic format for invoking these functions is 


Function: MOVD 
MOVD? 
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# Arguments: 3 


Arguments: 1) a function name, FROMFN 
2) a function name, TOFN 
3) a copy flag, COPYFLAG 


Value: The name of the TOFN atom (MOVD/MOVD?) ; 
otherwise, NIL. 


Note that MOVD works for EXPRs, compiled functions, and SUBRs. 
COPYFLAG, which is valid only for EXPRs, indicates that a copy of the func- 
tion definition will be used if it is T. Otherwise, a pointer to the EXPR list is 
placed in the TO-atom’s function definition cell. A new copy of the EXPR list 
allows us to edit the function definition as desired in case 1 above. 





A Definition for MOVD 
We might define MOVD as follows: 


(DEFINEQ 
(movd (fromfn tofn copyflag) 
(PROG (newflag) 
(SETQ newflag 
(NULL (GETD tofn) )) 


(PUTD tofn 
(COND 
(copyflag 
(COPY (GETD fromfn) )) 
(T 


(GETD fromfn) ))) 
(RETURN tofn) ) 
)) 


8.5.1 A MOVD Example 


Suppose we can apply one of several disjunction operators to a pair of argu- 
ments. One way to code this is to assign the name of the disjunction function to 
an atom and use that atom as the argument of a SELECTQ statement. For ex- 
ample 


«(SETQ disjunction-operator 
(QUOTE <a-disjunction-function)) ) 


«-(SELECTQ disjunction-operator 
(disjunct1 (disjunct1 a b)) 
(disjunct2 (disjunct2 a b)) 


(disjunctN (disjunctN a b))) 
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An alternative method would be to copy the function definition of the appro- 
priate function to the function definition cell of DISSUNCTION-OPERATOR. 
Then, we could code DISSUNCTION-OPERATOR uniformly in our program. 
The current definition would be applied to the arguments whenever a statement 
of the form 


(disjunction-operator a b) 


is executed. 
Consider the following definitions for possible disjunction functions: 


(DEFINEQ 
(disjunctO (a b) 
(COND 
((ZEROP a) b) 
((ZEROP b) a) 
‘) (T 1)) 


(DEFINEQ 
(disjunct1 (a b) 
(MIN 1 (PLUS a b)) 
)) 


(DEFINEQ 
(disjunct2 (a b) 
(DIFFERENCE 
(PLUS a b) 
(TIMES a b)) 


)) 


(DEFINEQ 
(disjunct3 (a b) 
(MAX a b) 
)) 


To set the current definition of DISSUNCTION-OPERATOR, we might use 
the following statement: 


(MOVD 

(SELECTQ <some condition) 
(0 (QUOTE disjunct0) ) 
(1 (QUOTE disjunct1) ) 
(2 (QUOTE disjunct2) ) 
(3 (QUOTE disjunct3) )) 

(QUOTE disjunction-operator) 

T) 
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To make this method as general as possible, we could package this state- 
ment as a function that can be called from anywhere in the program, 


8.6 FUNCTION PREDICATES 


INTERLISP provides several predicates for testing the type of a function. These 
predicates correspond to the values returned by FNTYP as discussed in Section 
8.1. Each predicate returns T if and only if its argument is one of the type indi- 
cated in the following table 


Function Predicates 


Predicate Truth Condition 

SUBRP SUBR, FSUBR, SUBR*, FSUBR* 
-CCODEP CEXPR, CFEXPR, CEXPR*, CFEXPR* 
EXPRP EXPR, FEXPR, EXPR*, FEXPR* 


also, if the argument has a list 
definition that does not begin with LAMBDA 
or NLAMBDA 


The general format for invoking these predicates is 


Function: SUBRP 
CCODEP 
EXPRP 


# Arguments: 1 


Argument: 1) a function name or a function 
definition, i.e., a list beginning with 
LAMBDA or NLAMBDA 
Value: T, if the truth condition in the table 
above is met; NIL otherwise. 


These predicates may be defined using FNTYP. 
Consider the following examples: 


«-(EXPRP 'CREATE.NODE) 


T 
<(CCODEP 'DEFINEQ) 
T 
«<-(SUBRP 'CAR) 
T 
A Definition for SUBRP 


We might define SUBRP as follows: 
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(DEFINEQ 
(subrp (a-function) 
(COND 
((SELECTQ (FNTYP a-function) 
((SUBR FSUBR SUBR* FSUBR*) T) 
\) (NIL) ))) 


The other functions are defined analogously. 


8.7 ARGUMENT LIST FUNCTIONS 


An INTERLISP function may or may not have arguments. When it does, it is 
sometimes useful to be able to obtain information about the arguments associ- 
ated with the function. Variable bindings are determined by function type 

1. If the function is a LAMBDA, each argument is bound to a value that 
results from enumerating and evaluating the expressions given in the ar- 
gument list of the calling expression. 
If the function is an NLAMBDA, the expressions in the calling expres- 
sion are not evaluated, but are bound directly to the atoms in the argu- 
ment list. 
If <arguments) in the function definition is NIL, the function receives no 
arguments when it is called. 


» 


2d 


4. If (arguments) in the function definition is a single atom, the arguments 
in the calling expression are gathered into a list and assigned as the value 
of that atom. Expressions in the calling expression’s argument list are 
evaluated or not depending on whether the function is a LAMBDA or 
NLAMBDA function. 


INTERLISP provides several functions to determine the characteristics of 
arguments that are passed to a function. 


8.7.1 Determining The Argument Type 


You may need to determine the type of arguments a function expects in order to 
construct the argument list to be passed to that function. Usually, this case 
arises when you are interfacing with code written by another user. ARGTYPE 
takes one argument—the name of a function—and returns an integer that speci- 
fies the type of function that it is or NIL if it is not a function. It takes the follow- 
ing form: 


Function: ARGTYPE 
# Arguments: 1 
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Argument: 1) a function name, FN 
Value: The argument type or NIL. 


The value of ARGTYPE is specified by the following table: 


Argument Types of Functions 


Value Function Type 
0 Lambda-spread 
me Nlambda-spread 
2 Lambda-nospread 
3 Nlambda-nospread 


Suppose that we have a function F1 that has been defined by another user, 
perhaps in a package that has been compiled. We do not know the type of the 
function nor do we care to visually inspect the code, if we could, to determine 
what the type of the function is. Nevertheless, we must use the function in our 
program. To do so properly, we have to construct an argument list to pass to the 
function. We might write a function in our own program called BUILD-ARGU- 
MENT-LIST that constructs the proper argument list based on the type of func- 
tion. 

A skeletal definition of BUILD-ARGUMENT-LIST might appear as fol- 
lows: 

(DEFINEQ 

(build-argument-list (a-function an-argument-list) 
(SELECTQ (ARGTYPE a-function) 
(0 (make-ls-list argument-list) ) 
(1 (make-ns-list argument-list) ) 
(2  (make-ln-list argument-list) ) 
(3. (make-nn-list argument-list) ) 
(NIL NIL)) 
)) 


where each of the functions MAKE... construct the proper argument list for the 
appropriate function type. 
To call the function F1, we would use APPLY: 


(APPLY f1 (build-argument-list f1 argument-list) ) 


Applying ARGTYPE directly to several standard INTERLISP functions, we 
see that it returns: 


«-(ARGTYPE 'DEFINEQ) 
3 
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*-(ARGTYPE 'ARGTYPE) 


0 
“(ARGTYPE 'PUTDQ) 
1 
«-(ARGTYPE 'IPLUS) 
2 


8.7.2 Determining the Number of Arguments 


You may also want to determine how many arguments a function requires when 
it is invoked. This knowledge is useful in constructing an argument list for a 
function. NARGS returns an integer that is the number of arguments in the 
function’s argument list or NIL if its argument is not a function. It takes the 
form 


Function: NARGS 

# Arguments: 1 

Arguments: 1) a function name, FN 

Value: The number of arguments or NIL. 


Its value is determined by: 


1. NIL, if FN is not a function. 

2. 0, if the argument list of FN’s definition is NIL. 

3. 1, if FN is a nospread function or has a single argument. 

4. N, which is the actual number of arguments expected by FN. 


Consider the following example: 


<(NARGS (FUNCTION build-argument-list) ) 
2 


because BUILD-ARGUMENT-LIST requires two arguments. 


«-(NARGS 'RECORDACCESS) 
y) 


«-(NARGS 'LOGOUT) 
0 


NARGS uses EXPRP rather than FNTYP. Therefore, NARGS will work on 
S-expressions that are not functions but which are lists. For example, 
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<(NARGS '(do-test a-list an-operation) ) 
2 


where DO-TEST has not been defined as a function. However, it appears to take 
two arguments (if it were treated as a function) and so the terms A-LIST and 
AN-OPERATION are treated as arguments to the presumed function DO- 
TEST. 


A Definition for NARGS 
We might define NARGS as follows (after INTERLISP/370): 


(DEFINEQ 
(nargs (fn) 
(COND 
((EXPRP (SETQ fn (CGETD fn))) 
(* 


If FN has a function definition 
or an EXPR property. Extract the 
argument list from the function 
definition. 


) 
(SETQ fn (CADR fn)) 


(COND 
((NULL fn) 
(* 
If the argument list 
is NIL, return zero. 
0) 
((ATOM fn) 
(* 
If the argument list 
is an atom, its a 
nospread function. : 
1) 


((NULL (CDR (LAST fn))) 
(* 


An argument list with 
some number of atoms 
representing 
arguments. 


) 
(LENGTH fn)) 
(T 
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(* 
The argument list has 
a dotted pair at its 
end. 


) 
(ADD1 (LENGTH fn))))) 
((CCODEP fn) 
(* 


The function is a compiled 
function, so look at the linkage 
to the function. This is machine 


dependent. 
) 
( LOGAND 
(LRSH 
(MKN 
(CAR (IPLUS 8 
(MKN fn) ))) 
8) 
255)) 


(T 

(* 
Functions defined as part of the 
underlying virtual machine have 
only one or two arguments. 

) 

(SELECTQ (FNTYP fn) 
((SUBR FSUBR) 2) 
((SUBR* FSUBR*) 1) 
NIL) )) 

)) 


where CGETD is defined as 


(DEFINEQ 
(egetd (fn) 
(COND 
((LITATOM fn) 
(GETD fn)) 
(T fn)) 
)) 


CGETD merely distinguishes between an atom, which is assumed to be the 
name of the function, and an S-expression, which is assumed to be a LAMBDA/ 
NLAMBDA form. 
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8.7.3 Obtaining the Argument List 


Given a function that you did not define, but which you wish to invoke, you may 
determine the argument list by executing the function ARGLIST. ARGLIST 
takes the form 





Function: ARGLIST 
# Arguments: 1 @g 
Argument: 1) a function name, FN | 
Value: The arguments for the function. 


ARGLIST returns a list of the arguments of the function which it takes as its 
argument. This function is particularly useful when you want to prompt the user 
for the values of arguments. 

The value it returns depends on the function type and definition 


1. NIL, if the function definition had NIL as its argument list specification. 

2. An atom, if FN is a nospread function. 

3. A list of atoms which are the names of the arguments that appeared in 
the function definition. 

4. An error message, ARGS NOT AVAILABLE, if FN is not a 
function. 


Consider the following examples: 


<(ARGLIST 'BREAKIN) 
(FN WHERE WHEN BRKCOMS) 


*-(ARGLIST 'ASKUSER) 
(WAIT DEFAULT MESS KEYLST TYPEAHEAD LISPXPRNTFLG 
OPTIONSLST FILE) 


Certain functions in various INTERLISP implementations are hardwired 
via assembly language (INTERLISP-10/VAX/370) or microcode (INTERLISP- 
D). Thus, the actual names of the arguments are not preserved in the sysout. In 
this case, ARGLIST ‘‘manufactures’” dummy argument names. For example, 


«(ARGLIST 'LIST) 
U 


<(ARGLIST 'RPLACA) 
(X Y) 


If FN is a compiled function, the argument list must be reconstructed from 
the arguments. Thus, each call to ARGLIST will cause the construction of a new 
list. 
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If FN is an atom with an EXPR property whose value is a list beginning with 
LAMBDA or NLAMBDA, ARGLIST returns the CADR of GETD of the value. 
ARGLIST also works if it is given a list whose CAR is LAMBDA or NLAMBDA. 
For example, 


mo "(LAMBDA (X) (ITIMES X X))) 
x 


8.7.4 Accessing the Arguments of a Nospread Function 


A nospread function has a single atom as its argument list specification. Any 
expressions appearing after the function name in the calling expression are eval- 
uated and their values are bundled into a list and bound to that single atom. To 
access individual arguments, you may use ARG which takes the form 


Function: ARG 
# Arguments: 2 


Arguments: 1) a variable name, VARX 
2) an index into the argument list, N 


Value: The value of the corresponding argument. 


ARG is an NLAMBDA function. VARX is the name of the atom that ap- 
peared in the nospread function’s definition. It may be any atom except NIL or 
T. It is not evaluated by ARG. N is an index into the argument list that specifies 
the number of the argument that you wish to retrieve. It is evaluated as follows: 


1. If N is less than or equal to 0, ARG returns NOBIND. 
2. If N is greater than the number of arguments, ARG returns NOBIND. 
3. ARG returns the value of the corresponding argument. 


Consider the following example (after the IRM): 


(DEFINEQ 
(xplus 
(LAMBDA varx 

(PROG ((ARGNUM 0) (ARGVAL 0)) 

loop 
(COND 

((EQ ARGNUM varx) 
(RETURN ARGVAL) )) 
(SETQ ARGNUM (ADD1 ARGNUM) ) 
(SETQ ARGVAL 
(PLUS ARGVAL 
(ARG varx ARGNUM) ) ) 
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(GO loop) ) 
))) 


Note that the variable VARX is bound to the number of arguments for a 
LAMBDA nospread function. When XPLUS is called, VARX is bound to 3. 
Thus, the test for terminating the loop succeeds. However, you should never 
reset the LAMBDA variable. Individual arguments may be reset via SETARG 
below. 

Consider the following example: 


«(XPLUS 10 30 50) 
90 


where we have the following correspondences: 
«(ARG varx 1) 
10 


(ARG varx 2) 
30 
(ARG varx 3) 
50 


and the value of VARX is 3. 


8.7.5 Setting the Arguments of a Nospread Function 


SETARG allows you to set the arguments of a LAMBDA nospread function 
from within the function. It takes the form 


Function: SETARG 
# Arguments: 3 


Arguments: 1) a variable name, VARX 
2) an index, N 
3) a value to be set, VALUE 


Value: The new value , 


SETARG is an NLAMBDA function. SETARG sets to VALUE the Nth ar- 
gument of the LAMBDA nospread function whose argument list is given by the 
atom VARX. VARX is not evaluated, but N and VALUE are evaluated. It is 
primarily used to modify the argument list prior to processing it within the func- 
tion. 


8.8 Function Evaluation 237 


8.8 FUNCTION EVALUATION 


INTERLISP operates in a READ-EVAL-PRINT loop. Expressions are read 
from the primary input file, evaluated, and the results are printed on the pri- 
mary output file. EVAL is the function which evaluates (e.g., ‘‘executes”) the 
expression and returns its value. EVAL takes the form 


Function: EVAL 

# Arguments: 1 

Arguments: 1) an S-expression, EXPRESSION 

Value: The value, if any, produced by evaluating 
EXPRESSION. 


EVAL takes one argument, EXPRESSION, which is an S-expression, that 
it gives to the intepreter for execution. Consider the following example: 


<(SETQ ex1 '(ITIMES X X X)) 
(ITIMES X X X) 


(SETQ X 20) 
20 


«(EVAL ex1) 
8000 


-exl 
(ITIMES X X X) 


EVAL is a LAMBDA function, so its argument is evaluated before being 
bound to EXPRESSION. EVAL is primarily used within functions where we 
construct an S-expression and then execute it. The following sections discuss 
some situations in which EVAL may be profitably used (some reference is made 
to concepts introduced in later chapters). 


8.8.1 Updating a Database Variable 


The File Package (see Chapter 17) uses a variable having the name (file) VARS 
to represent a list of variables that are to be “‘saved”” when a new version of the 
symbolic file is written. If your program processes several databases, you cannot 
hardwire the VARS variable into the code as some of the File Package functions 
expect. However, you may create your own updating function as follows: 


(DEFINEQ 
(add.to.database.variables (a.variable) 
(SET current.database.vars 
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(APPEND (EVAL current.database. vars) 
(LIST a.variable) )) 
)) 


where CURRENT.DATABASE. VARS holds the name of the VARS variable. 

Suppose we were maintaining a database about countries of the world. As- 
sume that we needed to add the variable PUERTO-RICO to the USA database. 
When the database is loaded, we would set CURRENT.DATABASE. VARS to 
USAVARS. Then, adding Puerto-Rico would merely involve 


«(add.to.database.variables 'puerto-rico) 
(maryland puerto-rico) 


Note that CURRENT.DATABASE. VARS has as its value the name of the 
file package variable. We evaluate this variable to obtain its value for updating. 


8.8.2 A-list Evaluation 


EVALA simulates a-list evaluation as it was performed in Lisp 1.5 [mcca72]. It 
takes the form 


Function: EVALA 
# Arguments: 2 
Arguments: 1) an expression, EXPRESSION 
2) a list of dotted pairs, ALST 
‘ Value: The value produced by evaluating 
EXPRESSION. 


EVALA spreads ALST on the stack. Each entry in ALST is a dotted pair 
consisting of a variable name and a value. EXPRESSION is evaluated using the 
“free” variables that appear on the stack as a result of spreading ALST. This 
form of evaluation was used in early LISP implementations. I recommend that 
you do not use it since its form and implementation are archaic. 


8.8.3 Constant Evaluation 


In some applications, you may need to specify functional arguments, but want 
them to evaluate to constants. INTERLISP provides functions that evaluate to 
the most frequently used constants. They take the form 


Function: NILL 
TRUE 
ZERO 
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# Arguments: 0 
Arguments: N/A 
Value: NIL, T, or 0, respectively. 


These functions are nospread functions that always produce the specified 
constants. 


8.9 FUNCTION APPLICATION 


One of the nice characteristics of INTERLISP is the ability to define a function 
dynamically, and then use that function to accomplish some result. In general, 
this capability is not available in most other conventional programming lan- 
guages. It is available because data structures and functions are just S-expres- 
sions in INTERLISP. So, to create a new function, we merely build an S-expres- 
sion of its definition and then evaluate it. A problem arises in telling the function 
about its arguments; that is, in setting up the proper calling sequence because 
the function has not been formally defined to INTERLISP via DEFINE. To 
solve this problem, we can use APPLY which takes a function definition and a 
list of arguments. It takes the following format: 


Function: APPLY 
# Arguments: 2 


Arguments: 1) a function definition, FN 
2) a list of arguments, ARGS 
Value: The result of applying FN to ARGS. 


FN may take several different forms: 
1. It may be the literal name of a function: 


«(APPLY 'PLUS '(5 6)) 
ta 


2. It may be a FUNCTION specification: 


«(APPLY (FUNCTION TIMES) '(5 6)) 
30 


3. It may be a LAMBDA or NLAMBDA definition: 


<(APPLY '(LAMBDA (x y) 
(CONS y x)) 
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‘(apples oranges) ) 
(oranges . apples) 


APPLY does not evaluate the individual elements of ARGS. Rather, it sim- 
ply calls FN with ARGS as the argument list. Thus, LAMBDA and NLAMBDA 
functions are treated exactly the same. 

APPLY is a LAMBDA function, so it evaluates its arguments before it is 
called. Suppose I have a set of functions for computing weighted conjunctions of 
two numbers which represent evaluations of two conditions. CONJUNCT com- 
putes the proper evaluations given two numeric operands, but its operation may 
vary with the state of the program. We might define CONJUNCT as follows: 


(DEFINEQ 
(conjunct (x y) 
(COND 

( (AND 
(NUMBERP x) 
(NUMBERP y) ) 
(APPLY *conjunct-operator* x y)) 

(T 


(ERROR "Non-numeric Arguments'') ) ) 
)) 


where *CONJUNCT-OPERATOR?¥ is a global variable whose value is the name 
of a conjunction function. 
We might define several conjunction functions as follows: 


(DEFINEQ 
(conjunct1 (x y) 
(COND : 
((EQP x 1.0) y) 
((EQP y 1.0) x) 
(T 0.0)) 
)) 
(DEFINEQ 


(conjunct2 (x y) 
(fmaximum 0.0 (PLUS x y (MINUS 1.0))) 
)) | 


(DEFINEQ 
(conjunct3 (x y) 
(PLUS 1.0 (TIMES x y)) 
)) 


Each function computes a different weighting of the variables X and Y. To 
select a function, we set its name as the value of *CONJUNCT-OPERATOR*. 
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«(SETQ *conjunct-operator* 'conjunct1) 
conjunct1 


<(conjunct 1.0 3.0) 
3.0 


«(SETQ *conjunct-operator* 'conjunct2) 
conjunct2 


<(conjunct 1.0 3.0) 
3.0 


(SETQ *conjunct-operator* 'conjunct3) 
conjunct3 


+(conjunct 1.0 3.0) 
4.0 


8.9.1 APPLYing to an Indefinite Number of Arguments 


Sometimes, the individual arguments to FN are produced separately in the call- 
ing program. To use these arguments in APPLY, you would have to invoke it in 
the following form 


(APPLY <FN) (LIST (argi) <arg2) ... <argN))) 


INTERLISP provides APPLY* as a shorthand notation for this form. It 
takes the format 


Function: APPLY* 
# Arguments: 1-N 
Arguments: 1) a function specification, FN 
2-N) arguments for FN 
Value: The result of applying Fn to ARGS[i] 


APPLY* is a nospread function. It is useful where the arguments are calcu- 
lated prior to applying the function. For example, you may have an expression of 
the form 


(APPLY*¥ (select-print-function) (select-print-arguments) ) 
which determines which printing function to apply to the specified arguments. 


8.10 REPETITIVE EXECUTION 


Many expressions are executed several times in a program in succession. Usu- 
ally, the expression maintains internal variables whose values change with each 
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iteration. Normally, you would have to set up a PROG loop to count the number 
of times that the expression is executed with a test to decide when you have iter- 
ated enough times. A shorthand notation for this mechanism is provided by 
RPT, which takes the form 


Function: RPT 
# Arguments: 2 


’ Arguments: 1) a repetition count, RPTN 
2) an expression, RPTF 


Value: The value resulting from the last 
evaluation of RPTF. 


RPT executes the expression RPTF for RPTN times. RPTN is counted down 
as each evaluation is performed. RPTF may use the value of RPTN to determine 
what to do at any given iteration. If RPTN is less than or equal to zero, RPTF is 
not evaluated; RPT returns NIL. 

An alternative form, RPTQ, is an NLAMBDA, nospread version of RPT. 
Its first argument, RPTN is evaluated to determine the number of iterations. 
The remaining N arguments are expressions which are not evaluated prior to 
calling RPTQ. At each repetition, RPTQ evaluates each of the RPTF[i] in suc- 
cession. Its value is the result of the last evaluation of the last expression, 
RPTF[N]. 

Consider the following examples: 


«-(RPT 10 '(PRINT RPTN)) 
10 
9 
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(the returned value) 


Note that RPTN is accessible in the expression that is executed by RPT. 
We can initialize an array to a specific constant using RPT as follows: 


<(SETQ Al (ARRAY 5 5)) 
{ ARRAYP }#546261 
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«-(RPT (ARRAYSIZE A1) '(SETA Al RPTN (ITIMES RPTN 100))) 
100 


which is the last value assigned because RPT counts down from the upper limit. 
Inspecting the value of A1[3], we see that it is 300: 


«(ELT Al 3) 
300 


A Definition for RPT 
We might define RPT as follows: 


(DEFINEQ 
(rpt (rptn rptf) 
(PROG (rptv) 
loop 
(COND 
( (IGREATERP rptn 0) 
(SETQ rptv (EVAL rptf)) 
(SETQ rptn (SUB1 rptn)) 
(GO loop) ) 
ee 
(RETURN rptv)))) 
)) 


8.11 GENERATORS 


Whenever you call a function in INTERLISP, it creates a stack frame (see Chap- 
ter 30) that exists for the duration of the function’s execution. When the function 
exits, the stack frame is released and all information concerning that activation 
is forgotten. If the function’s task is to compute a series of values, you must 


1. Compute all values and store them as a global variable. Functions exter- 
nal to the function that computed these values are responsible for access- 
ing the individual values. Or, 

2. Retain state information about the function in a global variable so that, 
at each invocation, the function can reestablish its previous state before 
computing the next value. 


The former method may be time-consuming if a large number of values 
must be computed. Moreover, if the next value to be computed depends upon 
some massaging of the previous value by an external function, it may not be 
possible to compute all the values at one time. The latter method introduces 
substantial complexity into the function which makes it difficult to comprehend 
as well as as leading to possible errors due to wrong implementation. 
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Generators are a mechanism for circumventing this problem. A generator is 
a function that retains state information (e.g., a history of its previous invoca- 
tions). 


8.11.1 Initializing a Generator 
GENERATOR is an NLAMBDA function that initializes a generator. It takes 
the format 

Function: GENERATOR 

# Arguments: 2 


Arguments: 1) an expression, FORM 
2) a generator handle, COMPVAR 


Value: A generator handle. 


GENERATOR creates a stack frame for FORM so that it may be called 
repeatedly. it returns a generator handle which is a pair of stack pointers. 
Consider the following example taken from the IRM [irm83]: 


+ (DEFINEQ 
(LISTGEN (1st) 
(IF lst 
THEN (PRODUCE (CAR 1st)) 
(LISTGEN (CDR 1st))) 


)) 
(LISTGEN) 
LISTGEN will produce elements of the list one at a time. 


«-(SETQ GR (GENERATOR (LISTGEN '(A B C)))) 
(#1,13442/#0 . #1,13444/GENERATOR) 


Each time GENERATE is called, it invokes PRODUCE to return the next 
value. 


«(GENERATE GR) 
A 


«(GENERATE GR) 
B 


«(GENERATE GR) 
C 


«(GENERATE GR) 
(#1,1342/#0 . #1,13444/#0) 


8.12 Macros 245 


When you have exhausted the input list, GENERATE returns the generator 
handle to indicate termination. 


“(GENERATE GR) 
,STACK POINTER HAS BEEN RELEASED 
#1,13444/#0 


PRODUCE and GENERATE take the following forms 


Function: PRODUCE 

# Arguments: 1 

Argument: 1) a value to be returned, VALUE 
Value: The value. 


PRODUCE is used from within a generator to return a value each time the 
generator is called. 


Function: GENERATE 
# Arguments: 2 


Arguments: 1) a generator handle, HANDLE 
2) a value, VALUE 


Value: The value to be returned. 


GENERATE restarts the generator given by HANDLE. VALUE is returned 
as the value of the PRODUCE which last suspended the operation of the genera- 
tor. When the generator runs out of values (if it does), GENERATE returns the 
value of HANDLE itself. 


8.12 MACROS 


When a function is called in INTERLISP, a new stack frame is created to estab- 
lish the environment in which the function will execute. Since INTERLISP does 
not distinguish between large and small functions, every function experiences 
this overhead. Sometimes, we need to parametrize very small pieces of code to do 
simple but diverse operations. Coding these code skeletons as fucntions forces us 
to pay the price of the function call. 

Macros allow us to create code skeletons which are expanded in-line to pro- 
duce efficient code. Macros are parametrizable, but invoking them does not 
cause a new stack frame to be created. They are akin to the in-line functions 
allowed in FORTRAN. Basically, executing a macro results in the creation of 
another piece of code which is then evaluated to produce a result. Thus, execut- 
ing a macro is a two-step process: macro expansion and resultant code evalua- 
tion. 
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Any literal atom may have a macro definition, just as it has a function defi- 
nition cell. The macro definition is stored on the atom’s property list as a list. 
The property name under which the definition is stored depends on the imple- 
mentation that you are using. Current property names include 3 


MACRO implementation independent macros 


10MACRO macros for INTERLISP-10 
DMACRO macros for INTERLISP-D 
VAXMACRO macros for INTERLISP-VAX 


8.12.1 Defining Macros 


A macro is defined by placing a value for a macro property name on the property 
list of a literal atom. Macro definitions can take several forms: 


1. Lambda or Nlambda forms 


When functions are compiled, they generate code that includes the 
overhead necessary to create a stack frame. You may force a function to 
compile open (e.g., generate in-line code) by placing a macro definition 
with LAMBDA or NLAMBDA on the atom’s property list. The defini- 
tion takes the usual form of a LAMBDA or NLAMBDA S-expression. 

Consider the code for REPLACADD which has the definition 


(DEFINEQ 
(replacaddd (x y) 
(RPLACA (LAST x) y) 
y)) 


and a test function, TEST1, defined as 
(DEFINEQ (TEST1 (X Y) (REPLACADDD X Y))) 


We may put the macro definition for REPLACADDD on its prop- 
erty list using 


(PUTPROP 'REPLACADDD 'MACRO (GETD 'REPLACADDD) ) 


Now, compiling TEST1, we see the following code (under IN- 
TERLISP-10): 


(TEST1 (x y) NIL) 
(ENTERF 2 0 0 0) 
(PUSHV x 0) 
(PUSHV y 1) 

(LAM 


-1 
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2 (RET) 
(LDV y 4) 
(VCLL y 5 RPLACA 2) 
(PUSHP) 
(VCLL x 4 LAST 1) 
(J 2) 


(BIND (x y) 2 0 2 2 NIL NIL T 2) 
) 
(RET) 


But, if we remove the macro definition from REPLACADDD’s 
property list via 


(REMPROP 'REPLACADDD 'MACRO) 
and recompile TEST1, we see the following code: 


(TEST1 (x y) NIL) 
(ENTERF 2 0 0 0) 

-1  (PUSHV x 0) 
(VCLL y 1 REPLACADDD 2) 
(RET) 


In the case of the macro definition, the code for REPLACADDD was 
compiled in-line to the definition of TEST1 whereas in the second case, a 
function call was generated. 


. Substitution Macros 


A substitution macro takes one of two forms: 


(NIL <expression) ) 
(<list>) <expression)) 


Each argument in the S-expression being evaluated or compiled is 
substituted for the corresponding atom in <list). The resulting expres- 


sion is used instead of the form. Consider the example given in the IRM 
[irm83] 


«-(PUTPROP 'ADDONE 'MACRO '((X) (IPLUS X 1))) 
((X) (IPLUS X 1)) 


(SETQ y '(5 6)) 
(5 6) 


+ (EXPANDMACRO (ADDONE (CAR Y))) 
6 
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- T Macros 


When a macro definition has the value T, the compiler ignores the 
macro definition and compiles the function definition instead. Normally, 
this will be used with atoms that have both a MACRO property and a 
specific implementation MACRO property, such as 1OMACRO. The 
MACRO property has the macro definition. If you want to run the func- 
tion on INTERLISP but the macro definition is valid only for IN- 
TERLISP-D, setting the DMACRO property to T instructs the compiler 
to ignore it when compiling the expression on INTERLISP-10 systems. 


. Synonym Macros 


You may instruct the compiler to treat one function as if it were an- 
other when compiling expressions by specifying MACRO properties of 
the following form: 


(= . (other-function-name) ) 


For example, INTERLISP-D compiles many of the functions begin- 
ning with F (for ‘‘fast’—see the IRM) exactly like their interpreted 
brethren (because of the way they are implemented in INTERLISP-D). 
Thus, FRPLACAs are treated exactly like RPLACAs. However, this ap- 
proach does not work with any of the other implementations because 
they compile into machine language. 

These types of macros may be used to define synonyms for functions. 
Suppose you frequently misspell the name of a function in a file. Rather 
than searching the file to replace all of the misspellings, you might place 
a synonym macro on the misspelling which specifies the correct function 
to be used in compiling the file. 


. Computational Macros 


A macro definition beginning with a literal atom other than those 
above causes the S-expression value to be evaluated or compiled in place 
of the form. This form is specified by 


(<literal-atom) <expression)) 
The literal atom receives the argument list to the macro. 


The IRM suggests that LIST could be compiled using the alternative 
form 


(X 
(LIST 'CONS 
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(CAR X) 
(AND (CDR X) 
(CONS 'LIST 
(CDR X))))) 


Thus, the expression (LIST ‘MOSES ‘ABRAHAM ‘ISHMAEL) 
would be compiled as 


(CONS MOSES 
(CONS ABRAHAM 
(CONS ISHMAEL NIL))) 


In this case, the macro expansion contains a recursive expression 
that allows it to deal with any number of arguments to LIST. 
For example, giving this macro property to TEST2: 


«-(PUTPROP 'TEST2 


"MACRO 
"(X 
(LIST 'CONS 
(CAR X) 
(AND (CDR X) 
(CONS 'LIST 


(CDR X)))))) 
(X (LIST 'CONS (CAR X) (AND (CDR X) (CONS 'LIST (CDR 


X))))) 


«-(TEST2 'MOSES 'ABRAHAM 'ISHMAEL) 
(MOSES ABRAHAM ISHMAEL) 


«(TEST2 10 20 30 40 50) 
(10 20 30 40 50) 


where X has taken the value (10 20 30 40 SO) prior to expanding the 
macro definition. 

If the literal atom evaluates to the litatom IGNOREMACRO, the 
macro is ignored and the compilation or evaluation proceeds as if there 
were no macro definition. 


8.12.2 Expansion of Macros 


Literal atoms may have both a function definition and a macro definition. When 
the interpreter evaluates an expression, it inspects the CAR of the expression. If 
the CAR of the expression has a function definition, that will be used (via a 
function call) to evaluate the expression. If it has a macro definition, then the 
expansion of the macro will be used to evaluate the expression. 
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The reverse is true during compilation. The macro definition is checked 
first. If it exists, it is used to generate the code for evaluating the expression, 
subject to the constraints mentioned above. If there is no macro definition, then 
the function definition is used. 

The IRM suggests that you may want to use a function definition that has a 
lot of error handling and debugging code for interpreted expressions during sys- 
tem development, but replace this by a fast in-line macro expansion when you 
compile the same expression (without the debugging code). 

_ Interpreted macros are implemented by the function MACROTRAN (for 
macro translation) which is an entry on DWIMUSERFORMS. If DWIM (see 
Chapter 22) is not enabled, MACROTRAN will not work. 

MACROTRAN is called if the CAR of an expression is undefined; that is, 
does not have a function definition. If the CAR of the expression has a macro 
definition, it is expanded and the result is evaluated in place of the original 
expression. The value of the expansion (an expression itself) is saved by 
CLISPTRAN (see Chapter 23) in CLISPARRAY so that the expansion need only 
be performed once. On subsequent findings, the expansion is retrieved from 
CLISPARRAY without invoking MACROTRAN. 

EXPANDMACRO is a function that is used to expand the macro definition 
of a literal atom and evaluate it during interpretation. It takes the form 


Function: EXPANDMACRO 
# Arguments: 2 


Arguments: 1) an expression, EXPRESSION 
2) a quiet flag, QUIETFLAG 


Value: The result of expanding the macro 
definition and evaluating it. 


The CAR of EXPRESSION must have a macro definition. This is expanded 
by EXPANDMACRO and evaluated. The result will be prettyprinted, unless 
QUIETFLAG is T, whence it is just returned. 

Consider the definition for TEST2 as demonstrated in the following exam- 


ple 


<(EXPANDMACRO '(TEST2 MATTHEW) ) 
(CONS MATTHEW NIL) 


8.12.3 A Function for Defining Macros 


Other LISP dialects provide functions for defining macros. For example, 
FranzLisp provides the function DEFMACRO which takes a form similar to a 
function definition. We might define DEFMACRO as follows 
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< (DEFINEQ 
(defmacro 
(NLAMBDA definition 
(PUTPROP (CAR definition) 
"MACRO 
(CDR definition) ) 
(CAR definition) 


))) 
(DEFMACRO) 


+ (DEFMACRO NEQ (A B) (NOT (EQ A B))) 
NEQ 


<-(GETPROP 'NEQ 'MACRO) 
((A B) (NOT (EQ A B))) 


«- (EXPANDMACRO '(NEQ X Y)) 
(NOT (EQ X Y)) 


+ (EXPANDMACRO (NEQ X Y)) 
T 


with X set to ABC and Y set to DFE. 
With this function, we may define two simple macros that treat a list like a 
stack. PUSH and POP have the following definitions 


«(DEFMACRO PUSH (VALUE STACK) 
(SETQ STACK (CONS VALUE STACK) )) 
PUSH 


<(DEFMACRO POP (STACK) 
(PROG 
(CAR STACK) 
(SETQ STACK (CDR STACK) ))) 
POP 


<-(SETQ STACK NIL) 
NIL 


<-(SETQ VALUE 'X) 
X 


«(PUSH VALUE STACK) 
(X) 

«(POP STACK) 

X 


STACK 
NIL 
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As we mentioned in Section 2.1, a literal atom is an indivisible unit of storage 
that is allocated by INTERLISP at the user’s request. Atoms have names, the 
PRIN1-NAME (PNAMEB), that are printed by INTERLISP. Two atoms that 
have the same PNAME have identical addresses in memory. Atoms are unique. 
The PNAME is defined as the sequence of characters that will be displayed by 
PRIN1. 

An atom may be characterized by a property list, a value, a function defini- 
tion, and a PNAME. Property lists and their manipulation are discussed in 
Chapter 7. Function definitions and their manipulation are discussed in Chapter 
8. This chapter discusses the creation and manipulation of atoms, and the print- 
ing of their names and values. 

The value cell of an atom is a set of memory locations that are allocated and 
_ assigned to an atom when it is given a value. An atom may be given a value in 
three ways: 


1. Referencing it as a variable via SETQ 
2. Specifying it as a function parameter 
3. Specifying it as a PROG variable 


An atom that has not been assigned a value has the atom NOBIND placed in 
its value cell. Thus, a value cell contains either an explicit value (one that fits 
into a computer word, such as an integer) or a pointer to a set of memory loca- 
tions that contain the atom’s value. 

Value cells cannot be directly referenced by the user. They must be accessed 
by referencing the atom as a variable. 

The PNAME of an atom is the collection of characters that represents the 
name of the atom as it appears when entered by the user or printed by the sys- 
tem. The length of the PNAME is implementation dependent. For example, 


(SETQ maryland NIL) 
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will create the atom MARYLAND if it did not previously exist in the system. The 
sequence of characters MARYLAND is the PNAME of the atom. The user refer- 
ences the value of this atom by typing MARYLAND to the top-level READ- 
EVAL-PRINT loop of INTERLISP. For example, 


“maryland 
NIL 


9.1 RULES FOR ATOM NAMES 


The length of the PNAME of a literal atom depends on the implementation. 
Currently, this length is 127 for INTERLISP-10, INTERLISP/VAX, and IN- 
TERLISP/370, and 255 characters for INTERLISP-D. Attempting to create a 
literal atom with a PNAME whose length exceeds these limits causes the error 
“ATOM TOO LONG” to be generated. 

Literal atom names are any sequence of characters that 


1. Cannot be interpreted as a number 
2. Are delimited by one of the following syntactic characters: 


space 

EOL end-of-line 

<LF) line feed 

( left parenthesis 
) right parenthesis 
" double quote 

[ left bracket 

] right bracket 


However, any character may be included in a literal atom name if it is pre- 
ceded by an (ESC) character, %. For example, we may create a rather unusual 
atom name via the following expression 


+(SETQ A%(BC%)D NIL) 
NIL 


which creates the atom A(BC)D. To ask INTERLISP to print its value, we must 
explicitly type the escape character before the left and right parentheses to indi- - 
cate they are part of the atom’s name. Thus, we must enter 


—A%(BC%)D 
NIL 


A PNAME is a collection of characters that are output when a pointer is 
printed using PRIN1 (see Section 15.1.1) or PRINT (see Section 15.1.3). This is 
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often referred to as the PRIN1-PNAME. PRINI does not print escape characters 
that might occur in the name. 

An alternative function, PRIN2 (see Section 15.1.2), prints all escape char- 
acters in the pointer’s name. PRIN2’s action may be modified by the action of a 
read table. 

The PNAME of an integer depends on the value of RADIX (see Section 
15.4.4). Integers are always printed by PRIN1 using the current value of RA- 
DIX. 

The number of characters permitted in a literal atom name allows you to be 
both expressive and creative. It is hard to underestimate the value of using good 
mnemonic names, and yet, you will find many INTERLISP programs that re- 
flect the influence of FORTRAN where only six characters were permitted. 

Good names, particularly when they reflect the usage of the variable, make 
a program easier to read. You may argue that you have to type in too many 
characters time after time, which is a tedious process. True, but given the ten- 
dency of INTERLISP programmers to fail to document their functions, lengthy 
names may help you remember what a function did weeks or months later. 

I have found that it helps me read my programs by breaking up the literal 
atom names with periods (.) or dashes (-). The latter works most of the time, but 
CLISP (see Chapter 23) does have a tendency to interpret such names as the 
subtraction of two variables. You might also consider using an underscore (__), 
but I have found that some printers do not display that character. Rather, they 
substitute a space which often leaves you wondering whether you are looking at 
two atoms or a single atom with an unprintable underscore. 

Consider some of the following atom names: 


candidate.goals 
deduce.plan.list 
lexical.scanner 
sentence.scanner 
number.of.characters 


It is unfortunate that most of the atom and function names used in IN- 
TERLISP do not follow this philosophy. You should contrast this with the read- 
ability of many ZetaLisp programs which use names broken into manageable 
segments as suggested above. 


9.2 CREATING ATOMS 


We have mentioned that atoms are normally created in three ways: 


1. via SETQ 
2. as a function parameter 
3. as a PROG variable 
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In each of these cases, the name of the atom is specified by you when you 
execute an INTERLISP statement. 

INTERLISP allows you to create atoms using three other functions: GEN- 
SYM, PACK, and MKATOM. 


9.2.1 GENSYM: Generating a Symbol 
You may create an atom using GENSYM, which takes the form 


Function: GENSYM 

# Arguments: 1 

Argument: 1) a character sequence, CHAR 
Value: A unique (usually) literal atom. 


GENSYM appends up to four digits to the character sequence to create the 
atom name. The form of the atom name is 


{character sequence)<digits) 


If the «character sequence) is NIL, INTERLISP uses the default character 
A. 

INTERLISP maintains an internal counter that is initialized to 10000. The 
current value of GENNUM, a system variable, represents the value that was 
used to create the last atom. GENNUM is incremented each time GENSYM is 
executed. Consider the following examples: 


<—GENNUM 
10000 


+ (GENSYM) 
A0001 


 (GENSYM) 
A0002 


<(GENSYM 'x) 
X0003 


*-(GENSYM 'help) 
HELP4 


Note that GENSYM suppresses the appropriate number of leading digits 
depending on the number of characters in its argument. Thus, when given the 
argument HELP above, GENSYM suppresses all leading zeroes, and merely ap- 
pends the nonzero digits. This may cause a problem if you use character se- 
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quences with four characters in them. Consider the following expression (A 
CLISP expression) and its results: 


«(FOR I FROM 1 TO 11 DO (PRINT (GENSYM 'HELP))) 
HELP1 
HELP2 
HELP3 
HELP4 
HELP5 
HELP6 
HELP7 
HELP8 
HELP9 
HELPO 
HELP1 


Note that the last atom name generated is not unique because GENSYM 
suppresses leading digits. Caution should be exercised when using GENYSM 
with character sequences larger than two or three characters if you expect to 
create many atoms. 

If the character sequence is five characters in length, GENSYM merely re- 
turns that character sequence. For example, 


<-GENNUM 
10011 
<-(GENSYM 'TRIAL) 
TRIAL 
but note that GENNUM is still incremented by one: 


<-GENNUM 
10012 


If the sequence is longer than five characters, GENSYM generates an error: 


<-(GENSYM 'PROCRASTINATION) 
ILLEGAL ARG 
PROCRASTINATION 


A Definition of GENSYM 
One possible definition of GENSYM might be as follows: 


(DEFINEQ 
(gensym (a-string) 
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(PROG (atom-prefix) 
(SETQ atom-prefix a-string) 
(COND 
((NULL atom-prefix) 
(* 


If no character sequence is 
specified, use the default. 


(SETQ atom-prefix 'A)) 
((GREATERP (LENGTH (UNPACK atom-prefix) ) 
5) 
(* 
Generate an error if the 
character sequence length is 
greater than 5 characters. 


) 
(PRINT "ILLEGAL ARG") 
(PRINT atom-prefix) 


(RETURN) ) ) 

(* : 
Generate the atom name and increment 
GENNUM. Note the use of PROG1. 

(RETURN 
(PROG1 
(SET 
(PACK 
(APPEND 
(UNPACK atom-prefix) 
(LASTN (UNPACK GENNUM) 
(DIFFERENCE 5 
(LENGTH 
(UNPACK atom-prefix) )) 
))) ; 
NIL) 


(SETQ GENNUM (ADD1 GENNUM))))) 
)) 


INTERLISP does not guarantee that the atom it creates will be unique. This 
situation may arise if you create atoms having the form specified above. Suppose 
the current value of GENNUM is 10056. Further, suppose you have previously 


created an atom JO0S7. If you execute 


<(GENSYM 'j) 
J0057 
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INTERLISP does not create a new atom J0057 because one alreay exists by 
that name. Assignment of a value to what you expected to be a new atom may, in 
fact, overwrite the value of the existing atom (possibly with disastrous conse- 
quences). Good programming practice dictates that you do not use atom names 
of this form in your programs. 

It is permissible to reset the value of GENNUM within your program, but 
you do so at some risk. In fact, if you follow the advice regarding the specifica- 
tion of atom names given above, you should never run the risk of conflict be- 
tween atom names created by GENSYM and those that you have created. 


9.2.2 MKATOM: Creating Atoms from Strings 


When executing programs, you may want to create atoms having names that are 
dependent on data read in or created by the program. For example, suppose you 
have a program that maintains a catalog of books by author. Entries in the cata- 
log are represented by atoms constructed from the author’s name. New entries in 
the catalog are made by reading the author’s name and manipulating it to create 
a new atom. 

We can create a new atom from the string representing the author’s name 
using MKATOM, which takes the following form 


Function: MKATOM 

# Arguments: 1 

Arguments: 1) an expression, EXPRESSION 

Value: A new atom whose pname is the characters 


comprising the string. 


If the value of EXPRESSION is not a string, INTERLISP applies MK- 
STRING to it. If this succeeds, MKATOM creates an atom, if one does not 
already exist, with the PNAME given by the value of the string. 

Consider the following examples: 


<(SETQ z "NOW IS THE TIME FOR ALL GOOD MEN'') 
"NOW IS THE TIME FOR ALL GOOD MEN" 


<(MKATOM 2) 
NOW% IS% THE% TIME% FOR% ALL% GOOD% MEN 


which is an atom with 32 characters in its name. The %s indicate that the spaces 
are valid characters in the name of the atom. 


«(SETQ x (LIST 'julius 'caesar) ) 
(julius caesar) 


<(MKATOM x) 
%(JULIUS% CAESAR%) 
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Note that the parentheses have been included as valid symbols in the name 
of the atom. This occurs because the result of evaluating (LIST ‘JULIUS 'CAE- 
SAR) is (SULIUS CAESAR) which is then given to MKSTRING. If the string 
has a length greater than that allowed for an atom name in the particular imple- 
mentation, the error ‘ATOM TOO LONG” will be generated. 


+ (SETQ x 3.141592) 
3.141592 


+ (MKATOM x) 
3.141592 


+ (MKATOM ''3.141592"') 
3.141592 


Numbers are literal atoms, by definition. No literal atom can have the 
PNAME of a number except the number itself. 


A Definition for MKATOM 
We can define MKATOM as follows: 


(DEFINEQ 
(mkatom (a-string) 
(PROG (the-string) 
(SETQ the-string a-string) 
(COND 
((NOT (STRINGP a-string) ) 
(SETQ the-string 
(MKSTRING a-string) ))) 
(RETURN 
(SET 
(CAR 
(PACK 
(UNPACK the-string) ) ) 
NIL) ) ) . 


)) 


9.2.3 Making an Atom from a Substring 


Given a string, you may make an atom name from a substring of the string using 
SUBATOM, which takes the form 


Function: SUBATOM 
# Arguments: 3 


9.2 Creating Atoms 261 


Arguments: 1) an expression, EXPRESSION 
2) a staring index, START 
3) an ending index, END 


Value: A literal atom name created from the 
substring extracted from the value of 
EXPRESSION. 


Usually, START and END are positive and characters are counted from the 
beginning of the string. If either START or END is negative, then that index is 
counted from the end of the string. 

If the value of EXPRESSION is not a string, MKSTRING is applied to it to 
create a string to which SUBSTRING is applied. 

Consider the following examples: 


«-(SETQ string "Washington was the father of his 
country"') 
"Washington was the father of his country" 


From this string we might extract a few substrings which become atoms in a 
database we are building from strings that are read into our program. For exam- 
ple, the key figure in this string is WASHINGTON, so we can extract his name 
as an atom via 


<(SUBATOM string 1 10) 
WASHINGTON 


«(SUBATOM string 20 25) 
FATHER 


If START or END is negative, it indicates a position counting backwards 
from the end of the string. Thus, we could extract FATHER as follows 


«-(SUBATOM string -21 -16) 
FATHER 


Note that if the value of the substring could be interpreted as a number, then 
the value of SUBATOM would be the corresponding number. Consider the fol- 
lowing example: 


+(SUBATOM "July 4, 1776" 9 -1) 
1776 


A Definition for SUBATOM 
We might define SUBATOM to be 
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(DEFINEQ 
(subatom (expression start end) 
(MKATOM (SUBSTRING expression start end)) 
)) 


9.3 PACKING AND UNPACKING ATOMS 


As we mentioned, an atom is an indivisible unit. But the name of an atom is 
merely a sequence of characters which, themselves, are indivisible units. We can 
break an atom name up into its constituent parts using the function UNPACK 
(sometimes called EXPLODE in other LISP systems). Conversely, we create 
atom names from a sequence of characters (or character codes) using the func- 
tion PACK (sometimes called IMPLODE in other LISP systems). 

PACK and UNPACK allow you to create atom names which represent both 
similarity and diversity. For example, the first N characters of a name could be 
the same indicating a similarity of purpose of the names, while the remaining 
characters are different indicating the different purpose of each of the atoms. 


9.3.1 Packing Atoms 


PACK concatenates any number of individual atom names into a single atom 
name. PACK takes the following form 


Function: PACK 
PACKC 
# Arguments: 1 
Argument: 1) a list of atoms, LST 
Value: An atom. 


In fact, PACK really concatenates the PNAMEs of the individual atoms in 
LST to form the PNAME of the result. If the argument is not a list, PACK gener- 
ates an error message: ILLEGAL ARG. Consider the following examples: 


«(PACK 'A) 

ILLEGAL ARG 

A 

«(PACK '(reagan)) 
REAGAN 

«(PACK '(1 3. 4)) 
13.4 


«(PACK '(1 E -3)) 
-001 


a 
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Note that if PACK produces the PNAME of a number as its result, when 
that PNAME is printed, it will appear correctly formatted by notation and radix. 

If the length of the resulting atom name is longer than the maximum allow- 
able atom name for your implementation, INTERLISP generates the error 
“ATOM TOO LONG”. 


A nospread version of PACK, PACK*, takes an indefinite number of argu- 
ments but avoids the CONSes required to form the result. It takes the form 


Function:. PACK* 

# Arguments: 1-N 

Arguments: 1-N) LISP objects 

Value: The concatenated result of the arguments 


as an atom's pname, if valid. 


PACK* is a nospread function. Consider the following examples: 
«(PACK* 'A 'Q 'U 'I 'N 'A 'S) 
AQUINAS 


+ ‘{ PACK 2°74.°7' G2) 
1.782 


Another variant, PACKC, takes a list of character codes and returns the 
alphanumeric equivalent of the PNAME. For example, 


<(PACKC '(45 67 89)) 
-?y 


9.3.2 Unpacking Atoms 


The converse function allows you to UNPACK the PNAME of an atom. Its value 
is a list of atoms corresponding to the PNAMEs of the characters comprising the 
PNAME of the argument. The generic format of UNPACK is 


Function: UNPACK 
# Arguments: 1-3 


Arguments: 1) an atom or string, ATM 
2) a flag, FLAG 
3) a read table, RDTBL 


Value: A list of atoms that comprise the PNAME of 
ATM. 
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Consider the following examples: 


<(UNPACK ' (washington) ) 
(washington) 


+ (UNPACK 3.141592) 
(3%.141592) 


<(UNPACK "BRIGADOON") 
(BRIGADOON) 


If FLAG is NIL, UNPACK produces a list of atoms corrsponding to the 
PRIN1-PNAME of the first argument. However, if FLAG has the value T, then 
the result corresponds to the PRIN2-PNAME of the first argument. The inter- 
pretation of the PRIN2-PNAME is modified by the RDTBL (see Section 14.4). 


<(UNPACK '(WASHINGTON) T) 
(40WASHINGTON2)) 


<(UNPACK '"BRIGADOON' T) 
(4'' BRIGADOON $") 


+ (UNPACK 3.141592 T) 
(3%.14159 2) 


Note that UNPACK will execute N CONSes where N is the number of char- 
acters in the argument to be unpacked. 


9.3.3 Using PACK and UNPACK 


The primary use of UNPACK is to produce a list of atoms that may be manipu- 
lated by other functions. . 

Suppose that you have a program that processes an input file to produce an 
output file. You prompt the user for the basic file name. Using this name, you 
generate an input file name that has the proper extension to distinguish the file 
types according to function. 

We can construct the function MAKE-INPUT-TEXT-FILE-NAME using 
PACK and UNPACK. This function assumes that the input file type is ‘*.text”’ 


(DEFINEQ 
(make-input-text-file-name (file-name) 

(PROG (input-file-name temp-file-name) 
(SETQ temp-file-name (UNPACK file-name) ) 
(SETQ input-file-name NIL) 

loop 
(COND 

((EQUAL (CAR temp-file-name) '.) 
(GO exit) ) 
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(T 
(TCONC input-file-name 
(CAR temp-file-name) ) )) 
(SETQ temp-file-name 
(CDR temp-file-name) ) 
(AND 
(NULL temp-file-name) 
(GO exit)) 
(GO loop) 
exit 
(RETURN 
(PACK 
input-file-name 
(UNPACK '.text)))) 
) 


And, when we execute this function 


«- (MAKE-INPUT-TEXT-FILE-NAME 'MONDALE-CAMPAIGN) 
MONDALE-CAMPAIGN . TEXT 


9.4 CHARACTER CONVERSION 


Converting between the numeric equivalent of a character and its PNAME for- 
mat is a useful function. There are two functions to accomplish this: CHCON 
and CHARACTER. 


9.4.1 CHCON: Converting to a Number 


CHCON converts the PRIN1-PNAME equivalent of an atom to a list of its nu- 
meric equivalents. This function is dependent on the character code used by the 
machine on which INTERLISP is implemented. Consider the following example 
(assuming EBCDIC): 


<(CHCON 'tungsten) 
(163 164 149 135 162 163 133 149) 


The generic format for calling CHCON is 


Function: CHCON 
# Arguments: 1-3 


Arguments: 1) an atom or string, ATM 
2) a flag, FLAG 
3) a read table, RDTBL 
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Value: A list of the numeric equivalents of the 
characters comprising the PNAME of the 
first argument. 


If FLAG has a value of T, the PRIN2-PNAME will be used instead of the 
PRIN1-PNAME. If the read table is non-NIL (see Section 14.4), it is used to 
interpret the characters in PRIN2-PNAME. 

An alternative form, CHCONI1, returns the character code of the first char- 
acter of the atom or string. CHCON1 does not use either the PRIN2-PNAME or 
the read table as CHCON does. It takes the form 


Function: CHCON1 

# Arguments: 1 

Argument: 1) an atom or string, ATM 

Value: The character code of the first character 


of the PNAME of ATM. 
Consider the following example: 


<(CHCON1 'tungsten) 
163 


A Definition for CHCON1 
We might define CHCON1 as follows: 


(DEFINEQ 
(cheon1 (atm) 
(NTHCHARCODE atm 1) 
)) 


9.4.2 CHARACTER: Converting to the PNAME Equivalent 


CHARACTER takes a single character code as its argument and returns the 
PNAME equivalent. It takes the form 


Function: CHARACTER 

# Arguments: 1 

Argument: 1) a character code, CC 

Value: The atom with the corresponding character 
as its PNAME. 


Consider the following examples: 
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«(CHARACTER 149) 
N 


(CHARACTER 202) 
J 


(CHARACTER 32) ° 
%<{ space) because 32 is the code for a blank! 


(CHARACTER 13) 
% because 13 is a line-feed. 


You should experiment with some of the non-printing characters to deter- 
mine their behavior when the corresponding character codes are given to CHAR- 
ACTER at the top level. 


9.4.3 Character Code Structures 


CHARCODE allows you to convert all the elements of an S-expression to charac- 
ter codes with one function. It takes the form 


Function: CHARCODE 

# Arguments: 1 

Argument: 1) an S-expression, EXPRESSION 

Value: An atom or list with all characters 
replaced by their corresponding character 
codes. 


CHARCODE is an NLAMBDA function. Consider the following example: 


-(CHARCODE x) 
88 


«-(CHARCODE "D"') 
68 


«(CHARCODE (MICHENE R)) 
(77 73 67 72 69 78 69 82) 


CHARCODE is especially useful when you must specify non-printing ASCII 
characters. A control character may be represented by preceding a character 
with (tT). For example, 


<(CHARCODE <T)B) 
2 
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If an atom or string begins with #, CHARCODE interprets it as an indica- 
tion of a meta-character. Normally, ASCII uses the integers 0 to 127 to represent 
characters. However, bytes are normally accorded a length of 8 bits, so there are 
another 128 integers (128-255) that are unused. By preceding a character with #, 
the character code that is returned is translated to the extended ASCII range. 
For example, ‘ 


-(CHARCODE #X) 
216 


CHARCODE provides atoms for the most frequently used non-printing 
characters: 


Character Code Atom 

13 CR 

10 LF 

32 SPACE, SP 

27 ESC, ESCAPE 
7 BELL 
8 BS (e.g., backspace) 
9 TAB 
0 NULL 

Dg DEL 


CHARCODE also maps NIL into NIL because some character manipula- 
tion functions can return NIL as their value. 


9.4.4 Character Translation 


One of the most difficult problems that many users face in transporting pro- 
grams from one computer system to another is the translation from one charac- 
ter set to another. There are two major character sets: ASCII and EBCDIC. 
ASCII is used by INTERLISP-10, INTERLISP/VAX, and INTERLISP-D. 
EBCDIC is used by INTERLISP/370. This section describes a character trans- 
lation function for converting from ASCII to EBCDIC (since it is the least fre- 
quent direction of conversion). 

The translation procedure may be defined as a table lookup procedure. We 
will use the character code of the ASCII character as an index into the table to 
determine the corresponding EBCDIC value. 

We may initialize the EBCDIC array as follows: 


(DEFINEQ 
(initialize-ebcdic-array NIL 
(PROG (ebcdic-table) 


(SETQ ebedic-table (array 256 0 'FIXP) 
(FOR I FROM 0 TO 75 
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DO 


(SETA 
(SETA 
(SETA 
(SETA 
(SETA 


(FOR I FROM 8 TO 89 


(SETA ebcdic-table I 
76 (CHCON1 
77 (CHCON1 
78 (CHCON1 
79 (CHCON1 
80 (CHCON1 


ebcdic-table 
ebcdic-table 
ebcdic-table 
ebcdic-table 
ebcdic-table 


DO 


(SETA 
(SETA 
(SETA 
(SETA 
(SETA 


(SETA ebcdic-table I I 
90 (CHCON1 ' 
! 
! 
! 
! 


ebcdic-table 
ebcdic-table 
ebcdic-table 
ebcdic-table 
ebcdic-table 


91 (CHCON1 
92 (CHCON1 
93 (CHCON1 
94 (CHCON1 


(FOR I FROM 95 TO 108 
DO 


(SETA 
(SETA 
(SETA 
(SETA 
(SETA 
(SETA 
(SETA 
(SETA 


I)) 
¢)) 
uty) 
'+)) 
')) 
'&)) 


(SETA ebcdic-table I I)) 
(SETA ebedic-table 109 (CHCON1 ' )) 
(SETA ebcdic-table 110 (CHCON1 '))) 
(SETA ebcdic-table 111 (CHCON1 '?)) 
(FOR I FROM 112 TO 120 
DO 


(SETA ebcdic-table I I)) 


ebcdic-table 
ebcdic-table 
ebcdic-table 
ebcdic-table 
ebcdic-table 
ebcdic-table 
ebcdic-table 
ebcdic-table 


(FOR I FROM 129 TO 
DO 


phen § 
122 
123 
124 
125 
126 
127 
128 
137 


(CHCON1 
(CHCON1 ':)) 
(CHCON1 
(CHCON1 
(CHCON1 
(CHCON1 '=)) 
(CHCON1 
128) 


(SETA ebcdic-table 


I 


(CHCON1 
(L-CASE 


(CHARACTER I) 


NIL)))) 
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Now, we have to be able to handle conversion of several different types of 
data objects. Our function to perform this translation for atoms is given below: 
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(DEFINEQ 
(convert.to.ebedic (x) 
(PROG (result) 
(COND 

((ATOM x) 

(RETURN 

(PACK 

(MAPCONC (UNPACK x) 
(FUNCTION lookup) )))))) 


)) 


As an exercise, you might consider how to include strings and lists as data- 
types to be handled by the COND clause. 


9.5 DETERMINING PNAME LENGTH 


When constructing a formatted buffer for printing, we often need to know the 
number of characters comprising the PNAME of an atom or string in order to 
avoid overflowing the buffer. INTERLISP provides NCHARS to tell us how 
many characters make up the PNAME of its argument. For example, 


<(NCHARS 'hydrogen) 
8 
<(NCHARS "einsteinium" T) 
13 
because the ‘‘s are included as part of the PNAME. 
«-(NCHARS 1756.7) 
6 
<-(NCHARS "Now is the time for all good men'') 
34 
The generic format for calling NCHARS is 


Function: NCHARS 
# Arguments: 1-3 


Arguments: 1) an atom or string, ATM 
2) a flag, FLAG 
3) a read table, RDTBL 


Value: The number of characters comprising the 
PNAME or NIL. 
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If the value of FLAG is T, then NCHARS uses the PRIN2-PNAME of its 
first argument. If RDTBL is non-nil (see Section 14.4), it is used to interpret the 
characters comprising the PRIN2-PNAME of its first argument. 

We can define a basic form of NCHARS for PRIN1-PNAMEs as follows: 


(DEFINEQ 
(nchars (argument) 
(COND 
((OR 

(ATOM argument) 
(STRINGP argument) 
(NUMBERP argument) ) 

‘ (LENGTH (UNPACK argument) ) )) 


9.6 EXTRACTING CHARACTERS 


You may want to extract the Nth character of the PNAME of an atom. NTH- 
CHAR takes the form 


Function: NTHCHAR 
NTHCHARCODE 


# Arguments: 4 


Arguments: 1) an atom or string, ATM 
2) an index, N 
3) a flag, FLAG 
4) a readtable, RDTBL 


Value: The Nth character of ATM otherwise, NIL. 


NTHCHAR returns the Nth character of the PNAME of ATM. N may be 
positive, whence the character is extracted relative to the beginning of the name, 
or negative, whence it is extracted relative to the end of the name. NTHCHAR 
returns NIL if N is greater than (NCHARS x) or less than (MINUS (NCHARS 
x)). For example, 


«-(NTHCHAR 'BALTIMORE 5) 
I 


«(NTHCHAR 'BALTIMORE) 
NON-NUMERIC ARG 
NIL 


because we have not specified any value for N. 
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«-(NTHCHAR "BALTIMORE" 5) 
I 


An alternative form, NTHCHARCODE, returns the character code of the 
Nth character. For example, 


«-(NTHCHARCODE 'BALTIMORE 5) 
73 


«-(NTHCHARCODE 'BALTIMORE 0) 
NIL 


«(NTHCHARCODE 1.345 3) 
51 


*-(NTHCHARCODE 'BALTIMORE -4) 
77 


If FLAG is T, either function uses the PRIN2-PNAME of ATM mediated by 
the read table (see Section 14.4). 


A Definition for NTHCHAR 
We might define NTHCHAR as follows: 


(DEFINEQ 
(nthchar (atm n) 
(COND 
((OR 
(ATOM atm) 
(STRINGP atm))) 
(T 
(ERROR "ILLEGAL ARG" atm) )) 
(COND 
((GREATERP (ABS n) 
(LENGTH (UNPACK atm))) 
NIL) 
((GREATERP n 0) 
(CADR (LASTN (UNPACK atm) n))) 
((LESSP n 0 
(CADR 


-_—_~ 


LASTN (UNPACK atm) 
(PLUS (LENGTH (UNPACK 


atm)) , 
n))))) 
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9.7 SELECTING ALTERNATIVES BY CHARACTER CODES 


Many applications use single characters as commands. SELCHARQ allows you 
to branch to different alternatives based on the value of a single character code. 
This function is also heavily used in writing communications software to assist in 
the deciphering of protocol characters generated by different host systems. It 
takes the form 


Function: SELCHARQ 
# Arguments: 2-N 
Arguments: 1) an expression, EXPRESSION 
2-N) clauses, CLAUSE[i] 
Value: The value of the last expression in the 


selected set of clauses. 


SELCHARQ operates like SELECTQ (see Section 3.6). However, it uses the 
character code equivalent of the value of EXPRESSION rather than the quoted 
character itself. Each clause takes the form 


(<key) <action)) 


where <key) is a single character or a list of characters to be matched against the 
value of EXPRESSION. When a match is found, all of the expressions appear- 
ing in action) are executed. The value of SELCHARQ is the value of the last 
expression executed in the clause. Matching is performed using EQ for single 
characters or MEMB for a list of characters. There must be a default clause 
which is the last clause in the list of selectors. If no match is found, the expres- 
sions in the default clause are executed. The value of SELCHARQ is then the 
value of the last expression executed in the default clause. 
SELCHARQ is an NLAMBDA, nospread function. 


9.8 CASE FUNCTIONS 


INTERLISP normally operates in upper case. That is, it accepts all commands 
and expressions in upper case. However, it makes provision for accepting lower 
case characters in certain instances. The body of a comment may be lower case 
as may the contents of a string. When matching strings, you must be careful to 
ensure that they correspond in case at every character position. Certain CLISP 
words may also be entered in lower case, whence CLISP performs the appopriate 
translation before executing the statement. 

INTERLISP provides several functions for translating from one case to the 
other and for testing the case of an object. 

L-CASE translates an object to lower case while U-CASE translates an ob- 
ject to upper case. They take the form 
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Function: L-CASE 
# Arguments: 2 
Arguments: 1) an object, X 
2) a flag, FLG 
Value: The lower case representation of X. 


L-CASE produces a lower case version of X. If FLG is T, the first letter will 
be capitalized. For example, 


«-(L-CASE 'WICHITA) 
wichita 


«<(L-CASE 'WICHITA T) 
Wichita 


<(L-CASE "FILE NOT FOUND'') 
"file not found" 


If X is a list, L-CASE returns a new list with L-CASE applied to each ele- 
ment of the list. For example, 


«-(L-CASE '(MONDAY TUESDAY WEDNESDAY THURSDAY FRIDAY) T) 
(Monday Tuesday Wednesday Thursday Friday) 


U-CASE takes the form 


Function: U-CASE 
U-CASEP 
# Arguments: 1 
Argument: 1) an object, X 
Value: An upper case representation of X. 


Consider the following example: 


«(U-CASE "As I was walking to St. Ives") 
"AS I WAS WALKING TO ST. IVES" 


You may test if an object is an upper case representation using the predicate 
U-CASEP. U-CASEP returns T if its argument, an object X, contains no lower 
case characters. Consider the following example: 


«-(U-CASEP '(SATURDAY SUNDAY) ) 
T 


10 


String Manipulation 
Functions 


A string is a sequence of zero or more alphanumeric and/or special characters 
that represents a literal value. Unlike atoms, strings do not represent memory 
locations within INTERLISP and, therefore, do not have values except the string 
representation itself. A string is demarcated by "' (double quote). A string may 
be assigned as the value of an atom. 

INTERLISP provides a comprehensive set of functions for creating and ma- 
nipulating strings. This chapter describes these functions and some applications 
demonstrating how strings may be used: 


10.1 CREATING A STRING 


The basic function for creating a string is MKSTRING, which takes the follow- 
ing format 


Function: MKSTRING 

# Arguments: 1 

Argument: 1) an atom or list, X 

Value: A string corresponding to the PRIN1-PNAME 
of X. 


Consider the following examples: 


< (MKSTRING) 
"NIL" 


<(MKSTRING 'x) 
nyn 


where the PRINI-PNAME of ‘X is X. 
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When a string is created, INTERLISP builds an internal data structure con- 
sisting of a string pointer and the sequence of characters that comprise the 
string. The string pointer contains the storage location where the sequence of 
characters begins and the number of characters comprising the string. Several 
string pointers may reference the same set of characters. String pointers may 
also point into the middle of a sequence of characters (as a result of CONCAT or 
SUBSTRING). This approach guarantees efficient management of string stor- 
age space. 

- We may also create a string by assigning it as a value to an atom. For exam- 
ple, 


<(SETQ a-string 
"Go therefore and make disciples of all nations'’) 
"Go therefore and make disciples of all nations" 


implicitly performs an MKSTRING to create the string data structure. The 
value of the atom is the string pointer. 

If we give MKSTRING a list as its argument, it makes a string of the whole 
list (including the parentheses). For example, 


<(SETQ proverb 
(LIST 'a 'stitch 'in 'time 'saves 'nine)) 
(a stitch in time save nine) 


<-(SETQ cliche (MKSTRING proverb) ) 
"(a stitch in time saves nine" 


But, this is not what we want! The result includes the parentheses. To rem- 
edy the situation, let us write a recursive procedure that converts a list into a 
string: 


(DEFINEQ 
(make.string.from.list (1st) 
(CONCAT (MKSTRING (CAR lst) 
(COND 
((NULL 1st) (MKSTRING) ) 
((make.string.from.list (CDR 1lst)))) 


)) 


Now, let us apply this function to the previous example: 


«-(SETQ cliche (MAKE.STRING.FROM.LIST proverb) ) 
"a stitch in time saves nine" 
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10.1.1 Allocating a String Pointer 


You may create a string pointer of a given length and initialize it to a default 
character value using ALLOCSTRING. It takes the form 


Function: ALLOCSTRING 
# Arguments: 3 


Arguments: 1) the length of the string, N 
2) the initialization character, INITCHAR 
3) an old string pointer, OLDPTR 


Value: A string of length N initialized to 
INITCHAR. 


INITCHAR must be a character code or an expression that is coercible to a 
character code. If INITCHAR is an atom, the first character of the atom is used 
as the initialization character. If INITCHAR is NIL, it defaults to the character 
code N (from NIL). Consider the following examples: 


<(ALLOCSTRING 1) 
mytt 
<(ALLOCSTRING 3 0) 


-(ALLOCSTRING 5 'B) 
"BBBBB" 


<-(ALLOCSTRING 10 'HELP) 
"HHHHHHHHHH" 

<(ALLOCSTRING 4 (LIST 'a 'b)) 
aCCKES 


< (ALLOCSTRING) 
NON-NUMERIC ARG 
NIL 


because a string must have a length greater than 0. 


10.2 EXTRACTING SUBSTRINGS 


Strings, from an external viewpoint, are indivisible objects in INTERLISP. That 
is, each function manipulates the entire contents of the string. However, we of- 
ten need to break strings down into their constituent parts (for example, when 
processing textual data). Two major operations are necessary: 
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1. Extracting a substring 
2. Peeling characters from the beginning or end of a string one-by-one 


10.2.1 The SUBSTRING Function 


Given a string, we can create a new string by extracting a portion of it—the 
substring operation. The function SUBSTRING allows us to extract pieces of a 
string. The format for SUBSTRING is 


Function: SUBSTRING 
# Arguments: 4 


Arguments: 1) an S-expression whose value is a 
string, STRING , 
2) the index of the first character of the 
intended substring, N 
3) the index of the last character of the 
intended substring, M 
4) an optional string pointer, OLDPTR 


Value: The specified substring; otherwise, NIL. 


SUBSTRING extracts the Nth through Mth characters of the string. If M is 
NIL, SUBSTRING extracts the Nth through last characters of the string. N may 
not be NIL. Both N and M may be negative numbers, thus referring to the end of 
the string rather than its beginning. 


«-(SETQ STR "WELCOME TO THE THEATRE") 
"WELCOME TO THE THEATRE" 


«(SUBSTRING STR 9 14) 
"TQ THE" 


«(SUBSTRING STR 16) 
"THEATRE" 


«(SUBSTRING STR NIL 7) 
NON-NUMERIC ARG 
NIL 


+ (SUBSTRING STR 14 9) 
NIL 


«(SUBSTRING STR -14 -9) 
"TO THE" 


If the string is not defined, e.g., then SUBSTRING applies MKSTRING to 
the first argument before extracting the subtring. 
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N and M must be well-defined according to the following conditions: 


N<(M 
N <¢ (NCHARS string) and M ¢ (NCHARS string), if M not NIL 
If N or M is negative, then N (or M) ¢ (MINUS (NCHARS string)) 


If OLDPTR is a string pointer, it is reused to perform the subtring op- 
eration; otherwise, a new string pointer will be created. 


10.2.2 Getting the Next or Last Character 


Many parsing programs, particularly command recognizers, need to extract 
characters from a string one-by-one. GNC allows you to get the next character 
from a string. GNC maintains an internal pointer to the string. It does not physi- 
cally remove characters from the string, but merely changes the pointer and the 
byte count. Thus, when you print the string, it appears as if characters have been 
removed because the pointer has been changed. 

If the argument is not a string, GNC applies MKSTRING to it before ex- 
tracting the specified character. If the argument is NIL or the null string, GNC 
returns NIL. 

GLC allows you to get the last character of a string. As with GNC, the 
pointer and the byte count are changed. Together, these two functions allow you 
extract characters from either end of the string. 

These functions take the following format 


Function: GNC 
GLC 
# Arguments: 1 
Argument: 1) a string, X 
Value: The next or last character of X. 


Consider the following example: 


«(SETQ z "Now is the time for all good men'') 
"Now is the time for all good men" 


«(for I from 1 to 32 do (PRIN1 (GNC z))(SPACES 1)) 
Nowisthetimeforallgoodmenz 


«(for I from 1 to 32 do (PRIN1 (GLC z))(SPACES 1)) 
nemdoogllarofemitehtsiwoNn 


+ (GNC) 
N 


because it applies (MKSTRING) which yields “NIL” and 


280 = String Manipulation Functions 


(GLC) 
L 


for the same reason. 
«(SETQ string "rumpelstiltskin"') 


"rumpelstiltskin"' 


«(GNC string) 
R 


“string 
"umpelstiltskin"' 


—(GLC string) 
N 


“string 
"umpelstiltski" 


Thus, if you need to preserve the original value of the argument, you should 
copy it before applying either GNC or GLC to it. Consider the following exam- 
ple: 


<(SETQ string "abc'') 
Napell 


«(GNC string) 
a 


«(GNC string) 
b 


«(GNC string) 
c 


«(GNC string) 
NIL 


because the value of STRING is now the null string. 


10.3 CONCATENATING STRINGS 
The functions in Section 10.2 allow you to take strings apart. CONCAT allows 
you to put two or more strings together into a new string. The format for CON- 
CAT is 

Function: CONCAT 


# Arguments: 1-N 
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Arguments: 1) a string, STRING[1] 
2-N) strings, STRING[2] ... STRING[n] 
Value: A new string composed of the individual 
arguments. 


CONCAT is a nospread function. CONCAT creates a new string pointer 
and copies each of the argument strings to the new string. If any of the argu- 
ments are not strings, CONCAT applies MKSTRING to it before copying. Con- 
sider the following example: 


< (CONCAT) 

went e.g., the null string. 
<(CONCAT "Baltimore" '"''"' 'is ' '" 'hest.) 
"Baltimore is best." 


10.3.1 Concatenating a List of Objects 


CONCATLIST concatenates a list of strings or other INTERLISP objects to 
form a string. It takes the form 


Function: CONCATLIST 

# Arguments: 1 

Argument: 1) a list of objects, LST 

Value: A new string that is the concatenation of 


the individual elements of LST. 


If the elments of LST are not strings, MKSTRING is applied to each in turn 
to produce a string which is concatenated into the result. Consider the following 
examples: 


 (CONCATLIST) 


mee 


which is the null string. 


«-(CONCATLIST (LIST 'a 'b 'c 'd 'e 'f)) 
'' ABCDEF" 


A Definition for CONCATLIST 
We might define CONCATLIST as follows: 


(DEFINEQ 
(concatlist (1st) 
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(APPLY (FUNCTION CONCAT) 1st) 
)) 


10.4 TESTING STRINGS 


There are two types of tests that we would like to apply to strings. The first deter- 
mines if the argument is a string. The second determines if two strings are equal. 


10.4.1 Determining String Existence 


STRINGP allows you to determine whether a given S-expression is a string or 
not. It returns the value of the S-expression if it is a string; otherwise, NIL. It 
takes the form 


Function: STRINGP 

# Arguments: 1 

Argument: 1) a string, STRING 

Value: The value of STRING if it is a string; 


otherwise, NIL. 
Consider the following examples: 
«-(STRINGP "Baltimore is best."') 


"Baltimore is best." 


 (STRINGP) 
NIL 


<(STRINGP 1.56) 
NIL 


10.4.2 Testing the Equality of Strings 
STREQUAL allows you to determine if two strings, X and Y, are equal. Equality 
is decided by determining whether or not the strings will print the same. Strings 
may be equal without satisfying EQ as explained in Section 4.6. STREQUAL 
takes the form 

Function: STREQUAL 

# Arguments: 2 


Arguments: 1) a string, X 
2) a string, Y 


Value: T, if the strings are equal. 





10.4 Testing Strings 283 


Consider the following examples: 


«-(STREQUAL "New York" "New York'') 


| 

(EQ "Washington" '"Washington'') 
NIL 

(EQUAL "Washington" ''Washington'') 
T 


Two separate string pointers are created by INTERLISP when strings are 
read in from the terminal (by RSTRING—see Section 14.2.4). Thus, the two 
string pointers in the example above are not EQ, although their contents are 
EQUAL. Note that EQUAL uses STREQUAL to determine the equality of two 
strings. 


10.4.3 Testing String Membership 


In many cases, we want to know if one string exists within another string. 
STRMEMB determines if its first argument, a string, is contained within its 
second argument, another string. It takes the form 


Function: STRMEMB 


# Arguments: 2 


Arguments: 1) a string, X 
2) a string, Y 


Value: The substring of Y, if X is contained 
within Y; otherwise, NIL. 


Consider the following examples: 


<(STRMEMB ''X'' "'TAX YEAR") 
"X YEAR" 


STRMEMB returns the substring of Y beginning with X if X is included 
within Y. 


A Definition for STRMEMB 
We might define STRMEMB as follows: 


(DEFINEQ 
(strmemb (x y) 
(PROG (achar index) 
(SETQ y (SUBSTRING y 1)) 
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loop1i 
(SETQ index 1) 
loop2 
(SETQ achar (NTHCHAR x index)) 
(COND 
((NULL achar) 
(RETURN y))) 
(COND 
((EQ achar (NTHCHAR y index) 
(SETQ index (ADD1 index) ) 
(GO loop2) )) 
(COND 
((NULL (GNC y)) 
(RETURN NIL)) 
(T (GO loopi)))) 
) 


10.5 REPLACING ELEMENTS OF A STRING 


In many programs, as we process strings, we want to replace characters in the 
string by new characters. RPLSTRING allows you to substitute characters 
within strings. The format of RPLSTRING is 


Function: RPLSTRING 
# Arguments: 3 


Arguments: 1) an original string, X 
2) the index of substitution, N 
3) the substitution string, Y 


Value: The modified version of the string X. 


RPLSTRING replaces characters in X beginning at the Nth character with 
characters from Y. Substitution continues until either Y is exhausted or the 
length of X is exceeded. Replacement is a one-for-one substitution of characters 
in X. If there is not enough room in X to accommodate the new string, an error 
occurs. X is physically modified by this operation. Note that if X is a substring of 
some other string, say Z, then Z is modified also. Thus, you should exercise 
caution concerning the indiscriminate modification of strings as a ripple effect 
may occur that was not intended. 

N may be positive or negative, but may not be greater than (NCHARS x). If 
either X or Y is not a string, it is converted to a string before the replacement 
operation is executed. In this case, a new string pointer will be returned, 


«(SETQ x "ABCDEF") 
"ABCDEF" 
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*-(RPLSTRING x -2 "Xyz!'') 
ILLEGAL ARG 
XYZ 


because inserting ““XYZ”’ into X would increase its length, which is not allowed. 


*-(RPLSTRING x 2 "XyYZ!'') 
"AXYZEF" 


Note that ““BCD”’ have been replaced by “XYZ”’. 


<(SETQ x 'BALITMORE"') 
"BALITMORE" 


which is misspelled! 


<(SETQ y (SUBSTRING x 3 6)) 
ULITM!" 


<—(RPLSTRING y 2 "TI") 
NLTIM" 


—x 


"BALTIMORE" 


where X is modified because Y was a substring of X. 
To insert without modifying the string, see INSERT.STRING in Section 
10.7. 


10.5.1 Replacing Elements with Character Codes 


An alternative form of RPLSTRING is RPLCHARCODE. RPLCHARCODE is 
used primarily to insert nonprinting character codes into strings. It takes the 
form 


Function: RPLCHARCODE 


# Arguments: 3 


Arguments: 1) an original string, X 
2) an index, N 
3) a character code, CHARCODE 


Value: A modified version of the string X. 
RPLCHARCODE is used to replace (or place) a single element of a string 


with a specified character code. The index N may be positive or negative. If N is 
negative, replacement is relative to the end of the string. 
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One of the most common string operations is to search one string looking for an 
occurrence of another string. STRPOS, which implements the string searching 
operation, takes the form 


Function: _ STRPOS 
# Arguments: 6 
Arguments: 1) a pattern string, PATTERN 


2) a string, STRING 

3) a starting position, START 

4) a skip (wild card) character, SKIP 
5) an anchor flag, ANCHOR 

6) a tail flag, TAIL 


Value: The character position in STRING if the 
match is successful. 


If either PATTERN or STRING is not a string, it is automatically converted 
(using MKSTRING) before searching begins. The search starts at the character 
indexed by START. If START is NIL, 1 is assumed. STRPOS looks for a se- 
quence of characters in STRING that match PATTERN. If a match is found, 
the character index of the first matching character of the sequence of characters 
is returned as the value of STRPOS. Otherwise, NIL is returned. Consider the 
following examples: 


<—(SETQ x "the quick brown fox jumped over the lazy dog") 
"the quick brown fox jumped over the lazy dog" 


<(STRPOS "fox" x) 
17 


<—(STRPOS "fox" x 10) 
17 


+-(STRPOS "fox" x 20) 
NIL 


<(STRPOS "fox"! X NIL) 
17 
«(STRPOS "fox" x -30) 
17 


hein (STRPOS tet ttt) 
NIL 


+ (STRPOS) 
1 
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Searching may be modified in several ways: 


1. SKIP is a character that acts like a wild card; that is, wherever it occurs 
in PATTERN it matches any character in,string in the corresponding 
position. SKIP may be any character but it is best to pick one that is not 
likely to occur in the string that you are searching. For example, 


+(STRPOS "br&wn'" x NIL '&) 
i By 


+-(STRPOS "dog&'' x 1 '&) 
NIL 


2. If ANCHOR is T, STRPOS searches for a match only at START (or 1, if 
START is NIL). If a match fails between PATTERN and the character 
sequence of STRING beginning at START, STRPOS returns NIL. For 
example, 


<—(STRPOS ''fox'' x) 
17 


«-(STRPOS "fox'' x 17 NIL T) 
a7 


<—(STRPOS "fox'' x 15 NIL T) 
NIL 


3. If TAIL is T, the character index returned by STRPOS is the index of the 
first character after the PATTERN was found in STRING, i.e., the tail 
string. For example, 


<(STRPOS "fox" x 1 NIL NIL T) 
20 


<(STRPOS "fox" x 17 NIL T T) 
20 


<(STRPOS "fox" x 15 NIL T T) 
NIL 


STRPOS may return a character position outside the string. For exam- 
ple, 


<(STRPOS "dog" x 1 NIL NIL T) 
45 


even though the string is only 44 characters long. Care should be taken in 
using this feature of STRPOS in conjunction with RPLSTRING because 
of the possibility of errors that may be generated by RPLSTRING. 
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A Definition of STRPOS 
We might define STRPOS as follows: 


(DEFINEQ 
(strpos (pattern string start skip anchor tail) 
(* 


Make PATTERN a string no matter what it is 
originally! 
) 


(COND 
((STRINGP pattern) ) 
((LITATOM pattern) 
(SETQ pattern (MKSTRING pattern) )) 
((NULL (STRINGP pattern) ) 
(SETQ pattern (MKSTRING pattern) ))) 
(* 
Make STRING a string no matter what 
datatype it is originally! 


(COND 
((STRINGP string) ) 
((LITATOM string) 
(SETQ string (MKSTRING string) )) 
(T 
(SETQ string (MKSTRING string) ))) 
(* 
The SKIP character must be a single 
character which the following code 
assures, no matter how many characters are 
provided. 
) + 
(COND 
(skip 
(SETQ skip (NTHCHAR skip 1)))) 
(* 
Orient START, if it is defined, to the 
beginning of the string. 


) 
(COND 
(start 
(COND 
((MINUSP start) 
(SETQ start 
(IPLUS start 
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(NCHARS 
string) 
1))))) 
ei 
( (SETQ. start 1))) 
x 
Now, isolate the proper substring to be 
searched rather than searching from the 
beginning of the string each time. 
(SETQ string 
, (SUBSTRING string start) ) 
x 


) 


(PROG (achar substring.x substring.y index) 
(SETQ index start) 


(* 


Search for PATTERN in STRING 


loop2 


Get the first character of the 
respective strings. 


) 
(SETQ substring.x (SUBSTRING pattern 1)) 
(SETQ substring.y (SUBSTRING string 1)) 


((SETQ achar (GNC substring.x) ) 
(COND 
((EQ achar (GNC 
substring.y) ) 
(GO loop1) ) 
((EQ achar skip) 
(GO loop1)) 
(T 
(GO next.character) ))) 
(tail 
(RETURN 
(IPLUS (NCHARS pattern) 
index) ) ) 
(T 
(RETURN index) ) ) 
next.character 
(* 
If no match in the exact position at 
START, cease further searching. 
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(COND 
(anchor 
(RETURN) ) ) 
(* 
Strip a character from STRING and 
proceed if any characters left to 
search. 
) 
(COND 
((GNC string) 
(SETQ index (ADD1 index) ) 
(GO loop2) ) 


(RETURN) ) ) ) 
)) 


10.6.1 Searching a String for a Character 


In many cases, you will want to search a string for the first occurrence of a char- 
acter which may be a member of a set of characters. STRPOSL, which compares 
a set of characters against a string until one matches, takes the form 


Function: STRPOSL 
# Arguments: 4 
Arguments: 1) a list of characters, CHARSET 


2) a string to be searched, STRING 
3) A starting index, START 
4) a non-membership flag, NEG 


Value: A character index or NIL. 


CHARSET may be a list of characters or character codes. STRPOSL 
searches STRING beginning at START (or 1, if START is NIL) for one of the 
characters in CHARSET. If one character matches, the character index of the 
matching character is returned. If no match occurs, NIL is returned. Consider 
the following example: 


«-(STRPOSL '(Q Z J) x) 
y) 


where X is defined as above. 
If NEG is T, then STRPOSL finds the first character which is not a member 
of ASET. 


oO eh 
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«(STRPOSL '(ABCDEFGHIKLMNOPQRSTUVX 
YZ) x17) 
4 


because SPACE is a legal character. If you insert a space at the end of the first 
argument (using the form %<space)), re-executing the expression yields 14, 
which is the index of W which does not appear in CHARSET. 


A Definition of STRPOSL 
We may define a simple form of STRPOSL as follows: 


(DEFINEQ 
(strposl (charset string) 
(PROG (index) 
(SETQ string (MKSTRING string) ) 
(SOME charset 
(FUNCTION strpos1) ) 
(RETURN index) ) 


)) 


where STRPOS1 is defined as 


(DEFINEQ 
(strpos1 (achar) 
(SETQ index (STRPOS achar string) ) 
)) 


10.6.2 Creating Bit Tables 


String searching is enhanced by converting the character codes to bit representa- 
tions. STRPOSL will automatically convert the characters (or their codes) in 
CHARSET into a bit representation if CHARSET is not a bittable. To do so, it 
uses the function MAKEBITTABLE, which takes the form 


Function: MAKEBITTABLE 


# Arguments: 3 


Arguments: 1) a list of character codes, CHARSET 
2) a non-membership flag, NEG 
3) an array, A 


Value: An array with bit representations for the 
characters in LST. 
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CHARSET is a list of characters or character codes as specified for STR- 
POSL. NEG is the same as used by STRPOSL. MAKEBITTABLE returns a bit 
table as an array containing the bit representations of the characters in CHAR- 
SET. For example, 


«-(SETQ charset '(ABCDEFGHIJ K)) 
(ABCDEFGHIJ kK) 


<-(SETQ y (MAKEBITTABLE charset) ) 
{ ARRAYP }#542635 


If A is an array, it is modified and returned as the new bittable to be used by 
STRPOSL. 


10.7 STRING OPERATIONS 


Given a string, we often want to insert, delete, or substitute for elements of the 
string. RPLSTRING can be coded to provide these functions, but it smashes the 
characters into the string given as its argument. The following functions provide 
similar capabilities, but return a new string composed of the appropriate ele- 
ments of the old. These functions are not part of standard INTERLISP at this 
time. 

These functions have been defined very simply. No doubt you can increase 
their complexity with a little extra thought. They are merely intended to show 
that you do not have to rely entirely on RPLSTRING for manipulating strings. 


10.7.1 Inserting into a String 
Given a string of arbitrary length, we often want to insert a new string into the 
middle of the string. INSERT.STRING takes the form 

Function: INSERT .STRING 

# Arguments: 3 


Arguments: 1) a string, X 
2) a fragment to be inserted, FRAGMENT 
3) a position, POS 


Value: A new string. 


INSERT.STRING inserts the fragment immediately after POS. Consider 
the example 


«-(INSERT.STRING "XYZ" "ABC" 1) 
"XABCYZ" 


¢ ——— So CU CS 
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A Definition for INSERT.STRING 
We might define INSERT.STRING as follows: 


(DEFINEQ 
(insert.string (x fragment pos) 
(COND 
((NOT (STRINGP x)) NIL)) 
(COND 
((NOT (STRINGP fragment) ) 
(SETQ fragment (MKSTRING fragment) ) )) 
(CONCAT 
(SUBSTRING x 1 pos) 
fragment 
. (SUBSTRING x (addi pos))) 


10.7.2 Deleting from a String 


DELETE.STRING deletes a substring from a string and returns a new string 
which is the concatenation of the remaining parts. It takes the form 


Function: DELETE.STRING 
# Arguments: 3 


Arguments: 1) a string, OLD 
2) a starting position, N 
3) an ending position, M 


Value: A new string with the appropriate 
characters deleted. 


Consider the following example: 


«-(DELETE.STRING ''ABCDEFG" 3 5) 
NABFG!" 


A Definition for DELETE.STRING 
We might define DELETE.STRING as follows: 


(DEFINEQ 
(delete.string (old n m) 
(CONCAT 
(SUBSTRING old 1 (SUB1 n)) 
(SUBSTRING old (ADD1 m))) 


)) 
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10.7.3 Substituting into a String 


SUBSTITUTE.STRING substitutes a fragment in place of a portion of a string. 
It takes the form 


Function: SUBSTITUTE .STRING 
# Arguments: 4 


Arguments: 1) a string, OLD 
2) a string to substitute, FRAGMENT 
3) a starting position, N 
4) a final position, M 


Value: A new string with FRAGMENT substituted for 
the substring identified by (N,M). 


Consider the following example: 


«-(SETQ string "ABCDEFG"') 
"ABCDEFG" 


«(SUBSTITUTE.STRING string "XYZ" 3 5) 
"ABXYZFG" 


A Definition for SUBSTITUTE.STRING 
We might define SUBSTITUTE.STRING as follows: 


(DEFINEQ 
(substitute.string (old fragment n m) 
(CONCAT 
(SUBSTRING old 1 (SUB1 n)) 
fragment — 
(SUBSTRING old (ADD1 m))) 
)) 


10.8 TRIMMING A STRING 


Many strings, particularly those created by reading or processing text files, con- 
tain an excess of blanks. Usually, we would like to eliminate these blanks in 
order to tidy up the appearance of the string. TRIM will remove the excess 
blanks from a string. It takes the following form 

Function: TRIM 

# Arguments: 1 


Argument: 1) a string, STRING 
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Value: A new string corresponding to STRING with 
all excess blanks removed. 


TRIM returns NIL if its argument is not a string. 


A Definition for TRIM 
We might define TRIM as follows: 


(DEFINEQ 
(trim (astring) 
(COND 
((NOT (STRINGP astring)) NIL))) 
(PROG (newstring bflag achar) 
(* 
Create an empty string in which to 
compose the return value. 
) 
(SETQ newstring (MKSTRING) ) 
loop 
(SETQ achar (GNC astring) ) 
(COND 
((NULL achar) 
(* 
GNC returns NIL when no 
more characters are left to 
process. 
) 
(RETURN newstring) ) 
((EQUAL (CHCON1 achar) (CHARCODE "' ")) 


(COND 
(bflag 
(* 
BFLAG set if we 
have seen one 
blank already. 
) 
(GO loop) ) 
(T 


(* 
Have not yet seen 
a blank. Set 
BFLAG to one and 
keep this blank. 


) 
(SETQ bflag T))) 
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(T 
(* 
Some character other than a 
blank. 


(SETQ bflag NIL))) 
(SETQ newstring (CONCAT newstring achar) ) 
(GO loop) ) 
)) 


Note: TRIM is not a standard INTERLISP function. 


a 


11 





Array Manipulation 
Functions 


Arrays are data structures that were added after the initial definition of LISP 
was developed. INTERLISP supports two types of arrays: basic linear arrays and 
hash tables. A linear array is a sequence of locations that contain values which 
are indexed by numerical position. A hash array is an array that relates two sets 
of pointers. The first pointer is known as the hash item while the second is called 
the hash value. Hash arrays operate in a manner similar to property lists in that 
they establish an association between the hash item and the hash value. 

In Section 11.4, we will show you how to define and manage matrices, which 
are two-dimensional arrays. INTERLISP does not provide support for this data- 
type. But, with a few functions, you can develop a comprehensive matrix han- 
dling package that operates like any other datatype. 


11.1 CREATING AN ARRAY: INTERLISP-10 


An array may only be created in INTERLISP through a function invocation. To 
create an array, you use ARRAY, which takes the following format 


Function: ARRAY 


# Arguments: 3 


Arguments: 1) Size of the array, N 
2) Number of value cells, P 
3) Number of pointer cells, V 


Value: A pointer to the array printed as 
{ ARRAYP }#{ address). 


When you execute (ARRAY n p v), INTERLISP allocates a block of storage 
of size N+2 words. The first two words contain descriptive information about 
the array that is used internally by INTERLISP. The next P {= N cells contain 


297 


298 = Array Manipulation Functions 


numeric values. Initially, the numeric cells have the value 0 when the array is 
created. Finally, the last N—P = ) 0 cells may contain pointers to list cells where 
both the CAR and CDR portions are available for storing information. They are 
initialized to the value of V. 


+-(SETQ Al (ARRAY 10 10 0)) 
{ ARRAYP }#542224 


«(SETA A1 1 (CONS 'X 'Y)) 
NON-NUMERIC ARG 
(X . Y) 


because only numeric information may be stored in the numeric (“‘unboxed’’) 
region of an INTERLISP-10 array. 

If P is NIL, INTERLISP assumes a value of 0 and creates an array of 
pointers. 


-(SETQ A2 (ARRAY 10 0 0)) 
{ ARRAYP }#542240 


«(SETA A2 1 (CONS 'X 'Y)) 
(% 3 ¥) 


«(ELT A2 1) 
Sao & 


«(SETA A2 1 (LIST 'A 'B 'C)) 
(A BC) 


«-(SETD A2 1 (LIST 'X 'Y 'Z)) 
(X Y Z) 


«-(ELT A2 1) 
(A BC) 


«-(ELTD A2 1) 
(X ¥ Z) 


In general, INTERLISP allocates storage for arrays from a common array 
space. If sufficient space does not exist for the array to be created, INTERLISP 
will attempt a garbage collection to gather space. If enough space is still not 
available, INTERLISP generates an error with the message “ARRAYS FULL”. 

The array facility provided by INTERLISP-10, INTERLISP/370, and IN- 
TERLISP-VAX< is more primitive than that provided by INTERLISP-D (as dis- 
cussed below). The number region of an INTERLISP-10 array may only store 
numbers, not pointers. These cells are not inspected during a garbage collection. 
All arrays in INTERLISP-10/370/VAX are indexed beginning with 1. 


a ee 
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11.1.1 Creating an Array: INTERLISP-D 


INTERLISP-D does not support the combined numeric value and pointer data 
structure. Rather, arrays have been extended so that you may specify the type of 
the value to be stored in the array. This approach provides you with more flexi- 
bility in using arrays to refer to collections of data. 

The format for defining arrays in INTERLISP-D is as follows: 


Function: ARRAY 
# Arguments: 4 


Arguments: 1) Size of the array, SIZE 
2) Type of the array, TYPE 
3) Initialization value, INIT 
4) Origin of the array, ORIGIN 


Value: A pointer to the array printed as 
{ ARRAY }#({ address) 


INTERLISP-D accepts a type from the following list: BIT, BYTE, WORD, 
FIXP, FLOATP, POINTER, or DOUBLEPOINTER. If the value of TYPE is 
NIL, INTERLISP-D creates an array with the default type of POINTER. If 
TYPE is a number (i.e., SIZE), INTERLISP-D defaults to an array of type FIXP 
(i.e., integers). 

The initialization value INIT is used to set the value of each element of the 
array when it is created. If INIT is NIL, zero is assumed for all numeric type 
arrays and NIL for all other types. 

Arrays in INTERLISP-D may have their origin indexed by either 0 or 1. If 
no origin is specified, the array will be indexed beginning with 1. 

For example, we may create an array called NUMBERS by the following 
statement: 


+(SETQ numbers (ARRAY 5 5)) 


{ ARRAYP }#1, 2150 

<(SETQ more-numbers (ARRAY 5 'FIXP 4 0)) 
{ ARRAYP }#1, 2140 

«(ELT more-numbers 0) 

4 


11.2 MANIPULATING ARRAYS 


INTERLISP provides several functions for manipulating arrays. Basically, these 
functions provide the user with a foundation for creating a rich and complex 
_ environment for specific applications. 
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11.2.1 Obtaining the Array Size 


You may obtain the size of an array by invoking the function ARRAYSIZE. It 
takes the form 


Function: ARRAYSIZE 

# Arguments: 1 

Arguments: 1) an array pointer, ARRAYPTR 
Value: The size of the array. 


INTERLISP generates an error, ARG NOT ARRAY, if the argument is not 
an array object (i.e., one created by the ARRAY function). For example, using 
NUMBERS 


<(ARRAYSIZE numbers) 
2 


11.2.2 Obtaining the Array Type 


INTERLISP creates arrays that contain either numeric value cells, pointer cells, 
or a mixture of both (INTERLISP-10/VAX). To obtain the type of the array, 
you may invoke the function ARRAYTYP with an array object as its argument. 
If the argument is not an array object, INTERLISP generates an error, ARG 
NOT ARRAY. It takes the form 


Function: ARRAYTYP 

# Arguments: 1 

Argument: 1) an array address, XARRAY 
Value: The second argument to ARRAY. 


ARRAYTYP returns the value of the second argument to ARRAY. If this 
value is a positive number greater than zero, it indicates the number of numeric 
values that may be stored in the array (INTERLISP-10/VAX). If this number is 
0 or NIL, it indicates that the array is composed entirely of pointers (IN- 
TERLISP-10/VAX). 


«-(ARRAYTYP A2) 
0 


which shows that A2 is an array defined to have only pointers as values. 

Thus, if you need to determine the number of pointers that may be stored in 
an array, you must compute this number by subtracting the value of ARRAY- 
TYP from ARRAYSIZE. We can encapsulate this in a function as follows 


—- = 
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(DEFINEQ 
(arrayptr (array-object) 
( IDIFFERENCE 
(ARRAYSIZE array-object) 
,) (ARRAYTYP array-object) ) 


ARRAYTYP is not defined in INTERLISP/370. 


INTERLISP-D Convention 
INTERLISP-D will return a value (i.e, the name of the datatype) that may be 
given to ARRAY (see above) that will generate the same type of array again. For 
example, using NUMBERS 


<(ARRAYTYP numbers) 
FIXP 


11.2.3 Validating an Array Pointer 


You may determine whether or not a pointer points to an array element by invok- 
ing the function ARRAYP. It takes the form 


Function: ARRAYP 

# Arguments: 1 

Arguments: 1) an array pointer, ARRAYPTR 

Value: The value of ARRAYPTR if it is an array 


pointer; otherwise, NIL. 


ARRAYP is a predicate that returns the value of the pointer if it points to or 
into an array. Otherwise, it returns NIL. INTERLISP does not check to see 
whether or not the argument actually points to the beginning of the array. For 
example, 


«(ARRAYP numbers) 
{ ARRAYP }#1, 2150 


11.2.4 Obtaining a Pointer to the Beginning of an Array 


Given a pointer to an array element, you may obtain a pointer to the beginning 
of the array by invoking the function ARRAYBEG. ARRAYBEG takes as its 
argument a pointer into an array. It returns a pointer to the beginning of the 
array if the pointer is valid. Otherwise, it returns NIL. 


302 Array Manipulation Functions 


INTERLISP-D does not support the function ARRAYBEG since it treats all 
arrays as linear objects of a given type. Rather, INTERLISP-D provides the 
function ARRAYORIG to return the origin of an array. It takes the form 


Function: ARRAYORIG 

# Arguments: 1 

Argument: 1) an array address, XARRAY 
Value: The origin of the array. 


Consider the following examples: 


(ARRAYORIG numbers) | "INTERLISP-D" 
1 

«-(ARRAYORIG A2) "INTERLISP-10"' 
1 


ARRAYORIG generates an error, ARG NOT ARRAY, if its argument does 
not satisfy ARRAYP. 

In INTERLISP-10/VAX, ARRAYORIG always returns 1. ARRAYORIG 
is not defined in INTERLISP-370. 


11.2.5 Setting the Value of an Array Element 


You may set the value of the Ith array element by invoking the function SETA. It 
has the following format: 


Function: SETA 
SETD 


# Arguments: 3 


Arguments: 1) an array object, A 
2) an index, I 
3) a value, V 


Value: The value assigned to the Ith array 
element. 


SETA sets the Ith element of the array A to the value V. If A is not an array 
object (i.e., returned by ARRAY), SETA generates an error ARG NOT AR- 
RAY. 


«(SETA a3 2 156) 
156 
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«(ELT a3 2) 
156 


If 1 <= P (from ARRAY), then the value of V must be numeric (i.e., satis- 
fies NUMBERP). If P <= 1 {= N, V is assigned to the CAR of the Ith element. 
The latter case determines if the Ith element is in the pointer region of the array. 


Note that pointers may not be inserted into the numeric regions of INTERLISP- 
10/VAX arrays. 


—(SETQ a3 (ARRAY 10 5 0)) 
{ ARRAYP }#542270 


<(SETA a3 2 (LIST 'ALEX 'ALICE 'ANDREA) ) 
NON-NUMERIC ARG 
(ALIX ALICE ANDREA) 


because 2 indicates a cell in the numeric (unboxed) region of A3. 


«(SETA a3 7 (LIST 'ALEX 'ALICE 'ANDREA)) 
(ALEX ALICE ANDREA) 


because 7 indicates a cell in the pointer region of A3. 

An alternative form of the function, SETD, will set the CDR of the Ith ele- 
ment of the array if I is an index within the pointer region of the array. For 
example, 


«(SETD a3 7 (LIST 'BARRY 'BART 'BILL)) 
(BARRY BART BILL) 


«(ELT a3 7) 
(ALEX ALICE ANDREA) 


because this list is stored in the CAR portion of the cell in the pointer region of 
A3 indicated by the index 7. 


INTERLISP-D Conventions 
Since INTERLISP-D supports typed arrays, I must always be less than or equal 
to N. 

INTERLISP-D supports SETD only to maintain compatibility with IN- 
TERLISP-10. It treats SETD as SETA when SETD is invoked. 

We can set the elements of the array NUMBERS using the following state- 
ments: 


«(SETA numbers 1 1) 
i 
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«(SETA numbers 2 2) 
2 


«(SETA numbers 3 3) 
3 


“(SETA numbers 4 4) 
4 


«(SETA numbers 5 5) 
5 


but when we attempt to set element 6: 


«(SETA numbers 6 6) 
ILLEGAL ARG 


because the array NUMBERS is defined to be only five elements in length begin- 
ning with the element labeled 1. 


11.2.6 Retrieving the Value of an Array Element 


You may retrieve the value of the Ith array element by BORING the function 
ELT. It has the following format 


Function: ELT 
ELTD 


# Arguments: 2 


Arguments: 1) an array object, A 
2) an index, I 


Value: The value of the Ith element of the array 


If I <= P (from ARRAY), ELT returns the numeric integer value contained 
in the Ith cell. If P < I <= N, ELT returns the CAR of the Ith element of the 
array. In the latter case, I is an index into the pointer region of the array. For 
example, 


«(ELT a3 7) 
(ALEX ALICE ANDREA) 


If A is not an array object, ELT generates an error ARG NOT ARRAY. 
An alternative form, ELTD, returns the CDR of the Ith array element if I is 
an index into the pointer region of the array. 


«(ELTD a3 7) 
(BARRY BART BILL) 
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INTERLISP-D Conventions 


Since INTERLISP-D supports typed arrays, the value of I must always be less 
than or equal to N. 

INTERLISP-D supports ELTD to maintain compatibility with IN- 
TERLISP-10. It returns the same value as ELT. For example, to retrieve ele- 
ment 3 from NUMBERS, 


«(ELT numbers 3) 


3 
«(ELT numbers 6) 
ILLEGAL ARG 


11.2.7 Copying Arrays 


You may copy the contents of an array, as opposed to creating a new pointer to 
it, by using the COPYARRAY function. It takes the form 


Function: COPYARRAY 

# Arguments: 1 

Arguments: 1) an array address, ARRAYPTR 

Value: An array pointer to the new array whose 
contents are an exact copy of the 
argument. 


COPYARRAY creates a new array of the same size and type as its argu- 
ment. Its value is a pointer to the new array. It generates an error message ARG 
NOT ARRAY if its argument is not an array. 

Consider the example 


«-(SETQ more-numbers (COPYARRAY numbers) ) 
{ ARRAYP }#5 , 33100 


«(ELT more-numbers 4) 
4 


but note that the two arrays are not EQUAL (since EQUAL does not perform 
these comparisons): 


«(EQUAL numbers more-numbers) 
NIL 
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11.2.8 Comparing Two Arrays 


Two arrays may be tested for equality using EQUAL. EQUAL determines equal- 
ity by determining if they have the same address. However, EQUAL does not 
descend into the two arrays to determine if the corresponding elements are 
equal. Thus, two arrays may be equal but not have the same address. Let us 
define a function EQARRAYP that determines if two arrays are equal according 
to the following criteria: 


The two arrays have the same length 

The two arrays have the same type of elements 

The two arrays have the same origin 

The two arrays have equal elements in each position 


The first three criteria are relatively easy to check and will probably account 
for most of the work performed by our function. 
EQARRAY?P takes the following form: 


Function: EQARRAYP 
# Arguments: 2 
Arguments: 1) an array, ARRAY1 
2) an array, ARRAY2 
Value: The address of ARRAY1 if the two arrays 


are equal; otherwise NIL. 


A Definition for EQARRAYP 
We might define EQARRAY?P as follows: 
(DEFINEQ 
(eqarrayp (array1 array2) 
(COND 
((OR 
(NOT (ARRAYP array1) ) 
(NOT (ARRAYP array2) ) ) 
(* 
If one of the arguments is not 
an array, return NIL. 
) 
NIL) 
((NEQ 


(ARRAYSIZE array1) 
(ARRAYSIZE array2) ) 


Sn a 
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)) 
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(* 
If the size of the arrays is not 
equivalent, return NIL. 
) 
NIL) 
((NEQ 


(ARRAYTYP array1) 

(ARRAYTYP array2) ) 

(* 
If the type of the arrays is not 
equivalent, return NIL. 


) 
NIL) 
((NEQ 

(ARRAYORIG array1) 

(ARRAYORIG array2) ) 

(* 
If the origin of the arrays is 
not equivalent, return NIL. 


NIL) 
(T 
(PROG NIL 
(FOR I 
FROM (ARRAYORIG array1) 
TO (SUB1 (ARRAYSIZE 
array1)) 
DO 
(IF 
(NOT 
(EQP 
(ELT array1 I) 
(ELT array2 I))) 
THEN (RETURN NIL) )) 
(RETURN array1)))) 


Note: EQARRAYP is not a standard function in INTERLISP, but one that 
you can easily define and save. 


11.3 HASH ARRAYS 


A hash array is an array where information is referenced by a hash item rather 
than a strict numeric index. The association between a hash item and the data it 


308 Array Manipulation Functions 


refers to is called a hash link. To use a hash array, INTERLISP computes an 
address, the hash address, in an array, called the hash array. At that location is 
stored the hash value, a pointer to the actual value of the data. The contents of a 
cell in the array are the hash item and the hash value, which together form a 
hash link. 

A hash array is used when the potential universe of items to be represented is 
large but the actual number of items to be stored and retrieved is rather small. 
Multiple item values may hash to a single cell in the array. It is assumed that the 
collision between keys is minimal; otherwise, a regular array representation 
might be more profitably used. 

When an item is hashed, the resulting hash address may already contain a 
hash link. INTERLISP determines if the entry was derived from the item just 
hashed. If so, the new value replaces the current contents of the cell. Otherwise, 
a new address is generated. This process repeats until an empty cell is found in 
which to place the hash link. When a hash array is seven-eighths full, it is either 
enlarged or an error is generated. 

Retrieving an item works in a similar fashion. A hash item is used to com- 
pute an address in the hash array. The item is compared against the hash item in 
the cell. If they match, the hash value is used to retrieve the desired value. Other- 
wise, a new address is computed and the process repeats until a hash link con- 
taining the item is found. If the hashing process generates a cell address whose 
entry is NIL, then no hash link exists for the item. 

INTERLISP provides a system hash array, SYSHASHARRAY, for you if 
you do not wish to create your own. It has an initial size of 512 cells. To use 
SYSHASHARRAY in the hashing functions, you must specify NIL as the value 
of the hash array address. 


11.3.1 Creating and Testing Hash Arrays 
You may create a hash array by executing HARRAY. It takes the form 


Function: HARRAY 

# Arguments: 1 

Arguments: 1) the number of cells, N 
Value: A pointer to the hash array. 


INTERLISP allocates storage for the hash array and returns a pointer to it 
of the form {HARRAYP}#x,abcde where the lower-case letters represent the 
storage address of the hash array. For example, 


«(SETQ a.hash.array (HARRAY 10)) "INTERLISP-D" 
{ HARRAYP }#7, 1030 
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You may test if a pointer refers to a hash array using the function HAR- 
RAYP. It takes the form 


Function: HARRAYP 

# Arguments: 1 

Arguments: 1) a hash array address, X 
Value: X, if it is a hash array address. 


HARRAYP returns the pointer if it indeed points to a hash array; otherwise 
NIL. For example, 


«(HARRAYP a.hash. array) 
{ HARRAYP }#7, 1030 


You may determine the number of cells in a hash array using the function 
HARRAYSIZE. It takes the form 


Function: HARRAYSIZE 

# Arguments: 1 

Arguments: 1) a hash array address, X 

Value: The number of cells in the hash array. 


Consider the following example: 


«(HARRAYSIZE a.hash.array) 
15 


INTERLISP-D automatically increases the initial size of the hash array by 
50% when it is created. Thus, although I created ALHASH.ARRAY of size 10, 
INTERLISP-D actually assigned it a size of 15. INTERLISP-10/VAX use a 
function dependent on the size of the hash array to determine the number of 
extra cells allocated. 

Hash arrays are not implemented in INTERLISP/370. 


11.3.2 Storing into and Retrieving from a Hash Array 
You may put an item into a hash array using PUTHASH. It takes the form 


Function: PUTHASH 
# Arguments: 3 
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Arguments: 1) a key, KEY 
2) a value, VALUE 
3) a hash array address, X 


Value: The new value. 


PUTHASH computes the hash address from KEY as described above. A 
hash link from KEY to VALUE is created and placed at the hash address. If a 
hash link already exists at that hash address, it will be overwritten by the new 
hash link. You may remove a hash link by specifying VALUE to be NIL. Hash 
values of NIL are not allowed. For example, 


+-(PUTHASH "'steve kaisler" "author" a.hash.array) 
"author"! 


«(PUTHASH "pete rose" "baseball iad a.hash.array) 
"baseball player" 


<-(PUTHASH "vanessa williams" "miss america" 
a.hash.array) 
"miss america" 


<(PUTHASH "rick dempsey" "world series mvp" 
a.hash.array) 
"world series mvp"! 


KEY may be any type of INTERLISP pointer—atoms, strings, array ad- 
dresses, lists, etc. If an INTERLISP object other than an atom is used as a key, 
the exact same item must be used to retrieve the hash value. This is required 
because INTERLISP compares the hash item stored in the cell with the key to 
determine if that key produced the hash value. The comparison is performed 
using EQ. 


Clearing a Hash Array 
You may clear a hash array that has been partially filled by executing the ee 
tion CLRHASH. It takes the form 


Function: CLRHASH 

# Arguments: 1 

Arguments: 1) a hash array address, X 
Value: The hash array address. 


CLRHASH removes the hash links in all cells of the hash array. It is a good 
idea to execute CLRHASH after you have created a hash array before storing the 
first hash link. 
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Retrieving an Element from a Hash Array 


You may retrieve a value from a hash array using the function GETHASH. It 
takes the form 


Function: GETHASH 
# Arguments: 2 


Arguments: 1) a hash key, KEY 
2) a hash array address, X 


Value: The hash value associated with KEY. 

GETHASH finds the hash link from KEY. It returns the value associated 
with the hash value in the hash link. If a hash link does not exist, it returns NIL. 
For example, 


«-(GETHASH "steve kaisler" a.hash.array) 


"author" 

<(PUTHASH (LIST 'alex) "the great" a.hash.array) 
"the great"! 

<(SETQ new.key (LIST 'alex)) 

(alex) 


which is a new list different from the one used in PUTHASH. So, 


«-(GETHASH new.key a.hash.array) 
NIL 


because the value of NEW.KEY is a different list from that used to create the 
hash link. 


Enlarging a Hash Array 

When a hash array becomes seven-eighths full, it may overflow (see Section 
11.3.5) or it may generate an error when you attempt to put a new value into it. 
You can catch the error using ERRORSET. If you do not wish to provide an 
overflow capability, you may expand the size of your hash array by copying it to 
another hash array of a larger size. REHASH hashes all items in one hash array 
into a new hash array. It takes the form 


Function: REHASH 
# Arguments: 2 


Arguments: 1) an old hash array address, OLDHARRAY 
2) a new hash array address, NEWARRAY 


Value: The new hash array address. 
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+-(SETQ a.new.hash.array (HARRAY 20) ) 
{ HARRAYP }#1, 2310 


«- (REHASH a.hash.array a.new.hash. array) 
{ HARRAYP }#1, 2310 


«-(GETHASH "vanessa williams" a.new.hash. array) 
"miss america"! 


11.3.3 Applying a Function to a Hash Array 


MAPHASH allows you to apply a function to each hash link in a hash array. It 
takes the form 


Function: MAPHASH 
# Arguments: 2 


Arguments: 1) a hash array address, X 
2) a mapping function, MAPHASHFN 


Value: The hash array address. 


MAPHASHEN is a function of two arguments: the hash value and the hash 
item. For each hash link in X, MAPHASHEN is applied to the hash value and 
the hash item. For example, to prettyprint the entire contents of a hash array, we 
might define the function 


(DEFINEQ 
(pp.hash.array (hasharray) 
(MAPHASH hasharray 

"(LAMBDA (hashvalue hashitem) 
(TERPRI) 
(PRINTDEF hashitem) 
(TERPRI) 
(PRINTDEF hashvalue) ) ) 


)) 


11.3.4 Dumping Hash Arrays 


You may dump a hash array using the function DMPHASH. This function is 
primarily intended to be used with the File Package to preserve the definitions of 
a hash array on a file for subsequent loading. It takes the form 


Function: DMPHASH 
# Arguments: 1-N 
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Arguments: 1) the names of hash arrays 


Value: The loadable expressions. 


DMPHASH is an NLAMBDA, nospread function that prints on the pri- 
mary output file a set of loadable forms that may be used to redefine a hash array 
when the file is subsequently loaded. 

If there are no arguments to DMPHASH, it assumes that you want to dump 
the system hash array, SYSHASHARRAY. 

Care must be exercised when reloading a hash array. READ creates new 
structures for each of the items and values that it reads from the file. Thus, all 
pointers except atoms and small integers will lose their EQ identities although 
they will retain their EQUAL identities. 

For example, to dump the system hash array, which you may use as your 
default hash array, you would place the following S-expression in your File Pack- 
age commands: 


(E (DMPHASH) ) 
Consider the following example: 


<(SETQ a.hash.array (HARRAY 10) ) 
{ HARRAYP }#151466 


<(PUTHASH (LIST 'ALEX) "the great'' a.hash.array) 
"the great!' 


<(DMPHASH a.hash. array) 

(RPAQ a.hash.array (HARRAY 11)) 
(PUTHASH '(ALEX) "the great'' NOBIND) 
NIL 


11.3.5 Overflow Handling 


When a hash array is created, it is given a definite size. As entries are made into 
the hash array, the hashing process becomes less efficient because new keys hash 
to slots that are already occupied by hash links. When a hash array becomes 
seven-eighths full (87.5%), INTERLISP considers it to be full. Attempting to 
add another hash link will cause a hash table overflow. 

When a hash table overflow condition occurs as the result of PUTHASH, 


either 


1. An error will be generated, or 
2. The hash array will be enlarged to accommodate additional keys. 


An error results if the last argument to PUTHASH is merely a hash array 
created by the user. Note if the hash array argument is NIL, SYSHASHARRAY 
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is used. It is automatically increased by 50% whenever an overflow condition 
occurs. 


To prevent an error, you must tell INTERLISP how to enlarge the hash ar- 


ray when an overflow condition occurs. The last argument to PUTHASH takes 
the alternative form 


(<hasharray) . <(expression)) 


where (expression) has one of the following values: 





{integer) A positive integer indicates that a new hash array is created | 
whose size is N cells greater than the old table. 
{floating #) A floating point number indicates that a new hash array is 
created whose size is equal to the size of the old table multiplied 
by the number. | 
{function) A function name or LAMBDA expression that is called upon 
hash table overflow. It takes one argument—the value of the 
last argument to PUTHASH. If the function returns a number, 
that number is used to create a new hash array of the given size. 
Otherwise, a new hash array is created that is 50% larger than 
the old hash table. | 
The function may be used to print a warning message, analyze the hash | 
array and delete some values, or monitor the function (via TRACE, for . 
example) that makes entries. | 


NIL A new hash array is created that is 50% larger than the old hash array. 


For example, assume that AAHASH.ARRAY is seven-eighths full. Then, let | 
us execute the following PUTHASH expression: | 


<(PUTHASH "carter" "ex-president" a.hash.array) 
HASH TABLE FULL 
{ HARRAYP }#7 , 1030 


| 
However, if we has used the specification for overflow handling: 
| 


<(PUTHASH "carter" "ex-president" (CONS a.hash.array 5)) 
"ex-president" 


«(HARRAYSIZE a.hash.array) | 
20 


where we remember that even though we specified 10 to HARRAY, IN- 
TERLISP-D automatically increased that by 50%. 
An alternative might be 
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<—(PUTHASH "carter" "ex-president'' (CONS a.hash.array 2.0)) 
"ex-president" 


+ (HARRAYSIZE a.hash.array) 
30 


Finally, let us look at an alternative using a function 


(PUTHASH "carter" 


"ex-president"' 
(CONS a.hash.array 
"(LAMBDA (x) 
(PRIN2 "Hash Array Overflow'') 
(TERPRI) 
(PRIN2 "Increase size by 3'') 
(TERPRI) 
(ITIMES (HARRAYSIZE a.hash.array) 
3)))) 


Hash Array Overflow 
Increase size by 3 
"ex-president" 


<—(HARRAYSIZE a.hash.array) 
45 


Note that the following construction causes an error: 


<(PUTHASH "carter" "ex-president" (LIST a.hash.array 2.0)) 
undefined function 


(2) 


because INTERLISP expects to find the value in the CDR cell as a result of 
CONSing the two values together. 


11.4 A MATRIX PACKAGE 


INTERLISP currently supports one-dimensional arrays, e.g., hash arrays. 
Many applications require two-dimensional arrays, e.g., matrices, for represent- 
ing data. This section describes a set of functions that you can use to define and 
manipulate matrices. These functions are not supported in standard IN- 
TERLISP. 


11.4.1 Defining a Matrix 


A matrix is a two-dimensional array, e.g., a array of arrays. The number of rows 
is independent of the number of columns. A special case is the square matrix 
where the number of rows is equal to the number of columns. 
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MATRIX creates matrices. It takes the form 


Function: MATRIX 
# Arguments: 4 


Arguments: 1) the number of rows, NROWS 
2) The number of columns, NCOLUMNS 
3) A data type, TYPE 
4) An origin specification, ORIGIN 


Value: An {ARRAYP} address representing the 
storage allocation for the matrix. 


MATRIX creates an array of NROWS elements. Each of these elements has 
as its value an array of NCOLUMNS elements. The address of the column arrays 
are stored as the values of the row elements. The address of the row array is 
returned as the address of the matrix. 

A matrix will have an origin of (0,0) or (1,1) depending on the value of ORI- 
GIN. If ORIGIN is NIL, an origin of (1,1) like that of FORTRAN is assumed. 
TYPE may be any of the legal values acceptable by ARRAY as specified in the 
INTERLISP-D manual. 

Consider the following example: 


<—(SETQ gnp (matrix 5 2)) 
{ ARRAYP }#7, 1044 


<—(for I from 1 to 5 
do (PRIN1 I) (SPACES 6) (PRINT (ELT gnp I))) 


1 {ARRAYP }#'7,1064 
2  {ARRAYP}#1,11310 
3 { ARRAYP }#7, 1070 
4 { ARRAYP }#'7,1104 
5  { ARRAYP }#'7,1110 
NIL 


where each of the elements of GNP is an array as expected. 


A Definition for MATRIX 
We might define MATRIX as follows: 


(DEFINEQ 
(matrix (nrows ncolumns type origin) 
(PROG (address index ilimit) 
(* 
Test for invalid values for number of rows 
and columns. 


—- woe - 


loop 


)) 
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(COND 
((LEQ nrows 0) 
(ERROR "negative or zero rows'')) 
((LEQ necolumns 0) 
; (ERROR "negative or zero columns'') )) 
x 


) 
(COND 
((NULL origin) 
(SETQ origin 1))) 


If no origin is specified, assume (1,1). 


(AND 
(NOT (IEQP origin 0)) 
(NOT (IEQP origin 1)) 
(ERROR "bad origin specification") ) 
(SETQ address 
(ARRAY nrows 'pointer NIL origin) ) 
(SETQ ilimit 
(COND 
((ZEROP origin) 
(SUB1 nrows) ) 
(T nrows) )) 
(SETQ index origin) 


(* 
For each element of the matrix row, create 
an array which represents the columns of 
that row. 


) 
(SETA address 

index 

(ARRAY ncolumns type NIL origin) ) 
(SETQ index (ADD1 index) ) 
(AND : 

(ILEQ index ilimit) 

(GO loop) ) 
(RETURN address) ) 


11.4.2 Getting a Matrix Element 


To retrieve a matrix element, you need to specify row and column indices. 
ELTM retrieves a matrix element. It takes the form 


Function: 


ELTM 


# Arguments: 3 
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Arguments: 1) a matrix address, NAME 
2) a row index, ROW 
3) a column index, COLUMN 


Value: The value stored at the row and column 
entry of the matrix. 


ELTM generates an error if 


1. The row index is less than 0 or greater than the number of rows. 


2. The column index is less than 0 or greater than the number of columns. 


3. NAME is not the address of a matrix. 
Consider the following example: 


«-(ELTM GNP 1 1) 
300 


A Definition for ELTM 
We might define ELTM as follows: 


(DEFINEQ 
(eltm (name row column) 
(AND 
(check.matrix name row column) 
(RETURN NIL) ) 
(ELT (ELT name row) column) 


)) 


where CHECK.MATRIX is defined by 


(DEFINEQ 
(check.matrix (name row column) 
(COND 
((NOT (matrixp name) ) 
(ERROR name "not a matrix''))) 
(COND 
((OR 
(ILESSP row 0) 
(IGREATERP row (ARRAYSIZE name) ) ) 
(ERROR "bad row index'') ) 
((OR | 
(ILESSP column 0) 
(IGREATERP column 
(ARRAYSIZE (ELT name 1)))) 
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(ERROR "bad column index") ) 
. (T name) ) 


11.4.3 Setting a Matrix Element 
To set a matrix element, you need to specify row and column indices. SETM sets 
the corresponding matrix element. It takes the form 

Function: SETM 

# Arguments: 4 


Arguments: 1) a matrix address, NAME 
2) a row index, ROW 
3) a column index, COLUMN 
4) a value, VALUE 


Value: The new value. 
SETM operates like ELTM except that it replaces the existing element of 


the matrix with the new value. 
Consider the following example: 


«(SETM GNP 1 1 300) 
300 


A Definition for SETM 
We might define it as follows: 


(DEFINEQ 
(SETM (name row column value) 
(PROG NIL 
(AND 
(check.matrix name row column) 
(RETURN NIL) ) 
(SETA (ELT name row) column value) 
(RETURN value) ) 
)) 


11.4.4 Basic Matrix Operations 


The basic operations that you may perform on two arithmetic matrices are addi- 
tion, subtraction, and multiplication. In addition, a matrix may be multiplied 
by a scalar. These operations are subject to certain conditions. Let M1 and M2 
be two matrices with dimensions (i1,j1) and (i2,j2) respectively. Then, 
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1. M1 and M2 may be added or subtracted provided il equals jl and i2 
equals j2. 

2. M1 and M2 may be mutiplied if il equals j2. The result has dimensions 
of (i1,j2). 


Adding or Subtracting Two Matrices 
Given two matrices, M1 and M2, with dimensions (i1,j1) and (i2,j2), respec- 
tively, MPLUS and MDIFFERENCE will add or subtract individual elements of 
the two matrices. They take the form 


Function: MPLUS 
MDIFFERENCE 

# Arguments: 2 

Arguments: 1) a matrix, M1 
2) a matrix, M2 

Value: The address of a new matrix whose elements 
are the sum or difference of the elements 
of Mi and M2. 


We can define MPLUS and MDIFFERENCE as follows: 


(DEFINEQ 
(mplus (m1 m2) 
(add.or.subtract.matrices m1 m2 T) 
)) 


(DEFINEQ 
(mdifference (m1 m2) 
(add.or.subtract.matrices m1 m2 NIL) 
)) 


The workhorse function that actually performs the operations is ADD.OR- 
-SUBTRACT.MATRICES which is defined as follows: 


(DEFINEQ 
(add.or.subtract.matrices (m1 m2 flag) 
(PROG (m3 i1 j1 i2 j2 index) 
( AND 
(is.matrix m1) 
(is.matrix m2) ) 
(SETQ i1 (ARRAYSIZE m1) ) 
(SETQ i2 (ARRAYSIZE m2) ) : 
(SETQ j1 (ARRAYSIZE (ELT m1 1))) 
(SETQ j2 (ARRAYSIZE (ELT m2 1))) 
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(COND 
((NEQ i1 i2) 
(ERROR "unequal row dimensions"') ) 
((NEQ j1 j2) 
(ERROR "unequal column 
dimensions"') )) 
(COND 
( (NOT 
(MEMBER 
(ARRAYTYPE (ELT mi 1)) 
'(FIXP FLOATP ...))) 
(ERROR mi "not an arithmetic matrix) ) 
( (NOT 
(MEMBER 
(ARRAYTYPE (ELT m2 1)) 
'(FIX FLOATP ...)) 
(ERROR m2 'not an arithmetic 


matrix"') ) ) 
(SETQ m3 
(MATRIX i1 j1 (ARRAYTYPE (ELT m1 1)) 
1)) 
rloop 
(SETQ index j1) 
cloop 
(SETM m3 
il 
index 
(COND 
(flag 
(PLUS (ELTM m1 i1 index) 
(ELTM m2 i1 index) )) 
(T 
(DIFFERENCE (ELT m1 il index) 
(ELT m2 il 
index) )))) 
(SETQ index (SUB1 index) ) 
(AND 


(GREATERP index 0) 
(GO cloop) ) 
(SETQ i1 (SUB1 i1)) 
(AND 
(GREATERP i1 0) 
(GO rloop) ) 
(RETURN m3) ) 


)) 
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Note that this definition does not consider whether or not both matrices have 
the same origin. As an exercise, add the code to test for equivalent origins. You 
will need to use the ARRAYORIGIN function to determine the origin. 


Multiplying Two Matrices 

Another operation that is often performed on matrices is multiplication. The 
usual procedure for multiplying one matrix by another is to compute the dot 
product of the rows of the first matrix with the columns of the second matrix. 
Using a transposition procedure, we can turn the columns of the second matrix 
into rows so that they are aligned with the rows of the first matrix. Then, a dot 
product procedure may be used on corresponding rows. MATRIX-MULTIPLY 
takes the form 


Function: MATRIX-MULTIPLY 
# Arguments: 2 
Arguments: 1) a matrix, MATRIX1 
2) a matrix, MATRIX2 
Value: A matrix that is the result of multiplying 


MATRIX1 by MATRIX2. 


MATRIX-MULTIPLY assumes the two matrices are of equivalent dimen- 
sions. As an exercise, you might want to recode it to handle two matrices of 
different dimensions. We might define MATRIX-MULTIPLY as follows: 


(DEFINEQ 
(matrix-multiply (m1 m2) 
(PROG (m3 i1 j1 12 j2 rindex cindex) 
(* 


RINDEX is the row index. 
CINDEX is the column index. 
M3 is the resulting matrix. 
) 
(AND 
(is.matrix m1) 
(is.matrix m2) ) 
(SETQ i1 (ARRAYSIZE m1)) 
(SETQ i2 (ARRAYSIZE m2) ) 
(SETQ ji (ARRAYSIZE (ELT m1 1))) 
(SETQ j2 (ARRAYSIZE (ELT m2 1))) 
(* 
Check the corresponding dimensions of 
the two matrices. 


11.4 A Matrix Package 323 


(COND 
((NEQ i1 i2) 
(ERROR "unequal row dimensions") ) 
((NEQ j1 j2) 
(ERROR "unequal column 
dimensions'') ) ) 
(* 
Check that the elements of the matrix 
are numeric so that the arithmetic 
operation will not fail. 
) 
(COND 
( (NOT 
(MEMBER 
(ARRAYTYPE (ELT m1 1)) 
'(FIXP FLOATP ...))) 
(ERROR mi "not an arithmetic matrix) ) 
( (NOT 
(MEMBER 
(ARRAYTYPE (ELT m2 1)) 
'(FIX FLOATP ...)) 
(ERROR m2 'not an arithmetic 
matrix'') ) ) 


Transpose m2's columns into rows. 


) 
(SETQ m3 (TRANSPOSE m2) ) 
rloop 
(SETQ rindex 1) 
cloop 
(SETQ cindex 1) 
eloop 
(SETA m3 
rindex 
cindex 
(DOT.PRODUCT (ELT m1 rindex) 
(ELT m3 cindex) ) ) 
(SETQ cindex (ADD1 cindex) ) 
(AND 
(NOT (GREATERP cindex j1)) 
(GO eloop) ) 
(SETQ rindex (ADD1 rindex) ) 
(AND 
(NOT (GREATERP rindex i1)) 
(GO cloop) ) 
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(RETURN m3) ) 
)) 


The TRANSPOSE Function 
TRANSPOSE merely exchanges rows for columns in the target matrix. We 
might define TRANSPOSE as follows 


(DEFINEQ 
(transpose (m1) 
(PROG (mt i1 j1 rindex cindex) 
(SETQ i1 (ARRAYSIZE m1)) 
(SETQ j1 (ARRAYSIZE (ELT m1 1))) 
(SETQ mt : 
(MATRIX it 
jl 
(ARRAYTYPE (ELT m1 1)) 1)) 
(SETQ cindex 1) 
rloop 
(SETQ rindex 1) 
loop 
(SETM mt 
cindex 
rindex 
(ELTM mi rindex cindex) ) 
(SETQ rindex (ADD1 rindex) ) 
( AND 
(GREATERP rindex i1) 
(GO loop) ) 
(SETQ cindex (ADD1 cindex) ) 
(AND 
(GREATERP cindex j1) 
(RETURN mt) ) 
(GO rloop) ) 
)) 


Note that this function could have been defined more easily using CLISP 
constructs (see Chapter 23). As an exercise, you may want to recode this function 
using CLISP. 


The DOT.PRODUCT Function 
DOT.PRODUCT merely multiplies elements of vectors together and accumu- 
lates their sum. We might define DOT.PRODUCT as follows: 


(DEFINEQ 
(dot.product (v1 v2) 
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(PROG (vsize vsum) 
(SETQ vsize (ARRAYSIZE v1) ) 
(SETQ vsum 0.0) 
vloop 
(SETQ vsum 
(PLUS (ELT v1 vsize) 
(ELT v2 vsize) )) 
(SETQ vsize (SUB1 vsize) ) 
( AND 
(ZEROP vsize) 
(RETURN vsum) ) 
(GO vloop) ) 
) 


Note that DOT.PRODUCT works backward through the two vectors. This 
eliminates the need for an additional temporary variable. 


11.5 SORTING USING ARRAYS 


We have already seen a sorting function that works on lists of elements (see Sec- 
tion 6.7). A typical operation that is often performed upon arrays is to sort their 
contents. In conventional programming languages, arrays are more often used 
than lists in sorting algorithms. Thus, this section presents a few simple sorting 
algorithms using arrays. 


11.5.1 BubbleSort 


The simplest sorting method known is called the bubblesort method because 
items ‘‘bubble up” from within the set when it is sorted in ascending order. We 
imagine an array of elements depicted in a vertical column. Elements with lower 
key values move up the column to the top of the array. Bubblesorting makes 
repeated passes over the array. At each pass, two adjacent elements are com- 
pared. If they are out of order; that is, the lower-valued one follows the higher- 
valued one, they are exchanged in place. As a result, after each pass the lowest 
value has been ‘“‘bubbled up” to its proper position in the array. 
BUBBLE.SORT takes the following form: 


Function: BUBBLE .SORT 

# Arguments: 1 

Arguments: 1) an array to be sorted, XARRAY 

Value: A new array whose contents are sorted in 


ascending order. 
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We might define BUBBLE.SORT as follows: 


(DEFINEQ 
(bubble.sort (xarray) 
(PROG (xsize element index) 

(* 
INDEX keeps track of the current 
element in the array that we are 
inspecting. 
ELEMENT keeps track of the starting 
element on each pass through the 
array. 3 

) , 

(SETQ xsize (ARRAYSIZE xarray) ) 

(SETQ element 1) 





loop 
(SETQ index element) 


(* 


test 


Compare the elements at INDEX and 
INDEX+1; if they are out of order, 
swap them. Note that INDEX does not 
exceed the limits of the array 
because of the test performed below. 
) 
(COND 
((GREATERP (ELT xarray index) 
(ELT xarray (ADD1 index) )) 
(SWAP xarray index) 
(SETQ element index) ) ) 
(SETQ index (ADD1 index) ) 
(* 


ee ee ee 


Determine if we have completed a pass 
through the array. 
) 
(AND | 
(LESSP index xsize) 
(GO test) ) 
(* 


) 
(COND 
((EQUAL element (SUB1 xsize) ) 
(RETURN xarray) ) 


Determine if sorting is completed. 


(T 
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(SETQ element (ADD1 element) ))) 
. (GO loop) ) 


SWAP merely exchanges two elements of the array in place given the index 
of the first element. We might define SWAP as follows: 


(DEFINEQ 
(swap (xarray index) 
(PROG (temp) 

(SETQ temp (ELT xarray index) ) 

(SETA xarray 
index 
(ELT xarray (ADD1 index) )) 

(SETA xarray 
(ADD1 index) 


temp) ) 
)) 


This definition of BUBBLESORT sorts a single set of numbers. I encourage 
you to embellish upon the definition in the following ways: 


1. Let the elements of the array be lists. Compare entries in the array based 
on the CAR of the list (i.e., the “‘key’”) and exchange them appropriately. 

2. Allow BUBBLESORT to accept a function which is the comparison 
function for the elements of the array. Since INTERLISP-D arrays can 
be different datatypes, you may specify different kinds of functions to 
perform the comparison. 

3. Attempt to define a recursive form of BUBBLESORT. Trace the opera- 
tion of this function to determine its behavior. 


11.5.2 Selection Sorting 


Selection sorting is an equally simple idea. In the Ith pass through the set of 
elements, we select the element with the highest key and swap it with the (N-I)th 
element (where N is the size of the set). As a result, after I passes through the set, 
the last I elements will be those elements with the highest keys sorted in ascend- 
ing order. SELECTIONSORT takes the following form: 


Function: SELECTION .SORT 

# Arguments: 1 

Argument: 1) an array to be sorted, XARRAY 
Value: The array XARRAY sorted in ascending 


sequence. 
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We might define SELECTION.SORT as follows: 


(DEFINEQ 
(selection.sort (xarray) 
(PROG (xsize maximum) 
(SETQ xsize (ARRAYSIZE xarray) ) 
loop 
(SETQ maximum 1) 
(PROG (element) 
(SETQ element. 1) 
loop2 
(COND 
((GREATERP (ELT xarray element) 
(ELT xarray xsize) ) 
(SETQ maximum element) )) 
(SETQ element (ADD1 element) ) 
( AND 
(LESSP element xsize) 
(GO loop2) ) 
(SWAP2 xarray maximum xsize) 
(SETQ xsize (SUB1 xsize)) 
( AND 
(EQP xsize 2) 
(RETURN xarray) ) - 
(GO loop) ) 


)) 


We might define SWAP2 as follows: 


(DEFINEQ 
(swap2 (xarray max.index last.index) 
(PROG (temp) 

(SETQ temp (ELT xarray max. index) ) 

(SETA xarray 
max. index 
(ELT xarray last. index) ) 

(SETA xarray last.index temp) ) 





)) 


Note that SWAP? takes two arguments for the locations of the elements to 
be swapped, whereas SWAP merely exchanges adjacent elements. 


12 





Mapping Functions 


INTERLISP provides two mechanisms for iteratively executing a function while 
varying the values of its arguments. In Chapter 3, we examined the PROG mech- 
anism which allowed us to develop models for the basic iterative control struc- 
tures: Unconditional DO, DO...WHILE, and DO...UNTIL. However, we had 
to explicitly set the new values of the arguments to a function before its next 
invocation. In this chapter, we shall examine mapping functions that apply a 
given function to successive subsets of its first argument. The form of the subset 
on each successive iteration is determined by the function. 


12.1 GENERIC MAPPING 
The basic mapping function is MAP. It has the following format 


Function: MAP 
MAPLIST 


# Arguments: 2-3 


Arguments: 1) a list, MAPX 
2) a function, MAPFN1, to be applied to 
successive subsets of MAPX 
3) a function, MAPFN2, for computing the 
successive subsets of MAPX 


Value: NIL for MAP; 
a list of values for MAPLIST. 


MAP operates by applying MAPFEN1 to the entire list MAPX, and then to 
(CDR MAPX) repeatedly until MAPX is exhausted. That is, MAP operates on 
the successive tails of MAPX. If MAPFN2 is non-NIL, INTERLISP computes 
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(MAPFN2 MAPX) rather than (CDR MAPX) for the successive subsets. 
MAPFNI1 may take several forms: 


1. A LAMBDA expression 
2. A FUNCTION expression 


3. A QUOTE expression whose argument is a function name or has an 
EXPR property value. 


Because MAP returns NIL as its value, it is primarily used for the side ef- 
fects generated by MAPFN1. MAPFN1 should do something positive such as 
setting a flag or changing a data structure when called from MAP. 

MAPFN1 and MAPFN2 may be any functions that take one argument. 
They may take more but, of course, these are assigned the value NIL. In general, 
MAPENI1 and MAPFN2 should check that their argument is a list before opera- 
ting upon the argument. 


A Definition for MAP 
We might define MAP as follows: 


(DEFINEQ 
(map (mapx mapfni mapfn2) 
(PROG NIL 
loop 
(COND 
((NLISTP mapx) 
(* 


MAP applies only to lists. 


) 
(RETURN NIL) )) 
(APPLY* mapfni mapx) 





(SETQ mapx 
(COND 
(mapfn2 
(* 
Use the user-supplied 
mapping function to 
generate next case. 
) 
(APPLY* mapfn2 mapx) ) 
(T 


(CDR mapx) ) )) 
(GO loop) ) 
)) 
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12.1.1 Returning a List of Values 


MAPLIST, an alternative form of MAP, executes exactly like MAP except that 
it returns a list of the results generated by applying MAPFN1 to MAPX. 
We might define MAPLIST as follows: 


(DEFINEQ 
(maplist (mapx mapfni mapfn2) 

(PROG (map.list map.expression) 
(SETQ map.list NIL) 

loop 
(COND 

((NLISTP mapx) 
(* 


MAPLIST works only on 
lists. 


) 
(RETURN map.list))) 
(* 
Results are CONSed to the front of 
the resulting list. 


(SETQ map.expression 


(CONS 
(APPLY* mapfni mapx) 
map.expression) ) 
(COND 
(map.list 
(RPLACD (CDR map.expression) 
(RPLACD 
map.expression) ) ) 
(T 
(SETQ map.list map.expression) ) ) 
(SETQ mapx 
(COND 
(mapfn2 
(APPLY* mapfn2 mapx) ) 
(T 
(CDR mapx) ))) 
(GO loop) ) 


)) 


Many alternative forms of MAP, designated in many texts as MAPxxx, are 
provided by INTERLISP. These are described in the following sections. It is 
useful to inspect the different definitions of the mapping functions to see how 
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minor changes in functions can produce new capabilities. We have included def- 
initions of the major MAP functions so that you may inspect them and use them 
as skeletons for developing more powerful mapping functions. 


12.1.2 Mapping on Successive Elements 


Many times we want to apply a function to successive elements of a list. IN- 
TERLISP provides the function MAPC to help us accomplish this task. MAPC 
applies MAPFN1 to (CAR MAPX) on each iteration. Its value is NIL. If 
MAPFEN2 is non-NIL, it is used in place of CDR to compute the new value of 
MAPxX. It takes the form 


Function: 


# Arguments: 
Arguments: 


Value: 





MAPC 
MAPCAR 


2-3 
1) a list, MAPX a | 
2) a function, MAPFN1, to be applied to 
succesive elements of MAPX 
3) a function, MAPFN2, for computing 
successive subsets of MAPX 
NIL for MAPC; ? 
a list of values for MAPCAR. ; 


An alternative form of MAPC is MAPCAR. It executes exactly as MAPC 
does, but returns a list of the values of the successive invocations of MAPFN1 on 
the elements of MAPX. Let us inspect how these functions work using MAP- 


CAR: 


«-(SETQ presidents '(tyler polk lincoln hayes) ) 
(tyler polk lincoln hayes) 


«-(MAPC presidents 'PRINT) 


tyler 
polk 
lincoln 
hayes 
NIL 


where NIL is returned as the value of MAPC. Alternatively, by invoking MAP- 


CAR, we obtain 


«-(MAPCAR presidents 'PRINT) 


tyler 
polk 


— 


— 
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lincoln 
hayes 
(tyler polk lincoln hayes) 


where the final list is the result of invoking MAPCAR because PRINT returns 
the value of the object printed. 
Because MAPCAR returns a list, it consumes storage to create the list. 


A Definition for MAPC 
We might define MAPC and MAPCAR as follows: 


(DEFINEQ 
(mape (mapx mapfni mapfn2) 
(PROG NIL 
loop 
(COND 
((NLISTP mapx) 
(* 
MAPC works only on lists. 


) 
(RETURN NIL) )) 
(APPLY* mapfni (CAR mapx) ) 
(SETQ mapx 
(COND 
(mapfn2 
(APPLY* mapfn2 mapx) ) 
(T 
(CDR mapx) ) ) ) 
(GO loop) ) 
)) 


(DEFINEQ 
(mapear (mapx mapfni mapfn2) 

(PROG (map.list map.expression) 

(SETQ map.list NIL) 
loop 

(COND 

((NLISTP mapx) 
(* 
MAPCAR works only on lists. 


) 
(RETURN map.list) )) 
(SETQ map.expression 
(CONS (APPLY* mapfn1 
(CAR map.expression) ) 
map .expression) ) 
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(COND 
(map.list é 
(RPLACD (CDR map.expression) 
(RPLACD 
‘ map.expression) ) ) 
(SETQ map.list map.expression) ) ) 
(SETQ mapx 
(COND 
(mapfn2 
(APPLY* mapfn2 mapx) ) 
T 
(CDR mapx) )) ) 
‘ (GO loop) ) 


12.1.3 Mapping on Successive Elements: MAPCONC 


We noted that MAPCAR always returns a new list containing the results of its 
execution. Sometimes, we want to modify the list that is presented as an argu- 
ment. To do so, we use MAPCON or MAPCONC which NCONC the results of 
applying MAPFNI1 to MAPX onto the original list. They take the form 


Function: MAPCON 
MAPCONC 


# Arguments: 2-3 


Arguments: 1) a list, MAPX 
2) a function, MAPFN1, to be applied to 
succesive subsets (MAPCON) or CARs 
(MAPCONC) of MAPX 
3) a function, MAPFN2, to be used to 
compute the succesive subsets of MAPX 


Value: A list of values of the successive 
applications of MAPFN1 NCONCed together. 


MAPCON computes the same values as MAP/MAPLIST but NCONCs the 
values to form a list which it returns. MAPCONC computes the same values as 
MAPC/MAPCAR in the same manner. Consider the following examples: 


«(SETQ X '(Pelee Etna NIL Vesuvius NIL NIL Krakatoa) ) 
(Pelee Etna NIL Vesuvius NIL NIL Krakatoa) 


«-(MAPCONC X 
"(LAMBDA (x) 
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(COND 
((NULL x) NIL) 


(T (LIST x))))) 
(Pelee Etna Vesuvius Krakatoa) 


This MAPCONC expression strips null elements from a list and returns a 
list of the non-null elements. 


“(SETQ X 
'((Rome New-York) Milan (Bonn Moscow Paris) 
Lisbon) ) 

((Rome New York) Milan (Bonn Moscow Paris) Lisbon) 


<(MAPCONC X 
"(LAMBDA (X) 
(COND 
((LISTP x) (APPEND y)) 
((ATOM x) (LIST x)) 
(T NIL)))) 
(Rome New-York Milan Bonn Moscow Paris Lisbon) 


This MAPCONC creates a linear list of all elements in lists or atoms which 
are present in the argument. Since MAPCONC is NCONCing the results to- 
gether, it will alter the original input list. To prevent this undesirable side‘effect, 
the APPEND expression returns a top-level copy of the argument. 


A Definition for MAPCONC 
MAPCONC may be defined using several elementary functions of INTERLISP. 
A possible definition for MAPCONC might be 


(DEFINEQ 
(MAPCONC (mapx mapfni mapfn2) 
(PROG (mapl mape mapy) 
loop 
(COND 
((NLISTP mapx) 
(* 
MAPCONC works only lists. 


(RETURN map1) ) 
((SETQ mapy 
(apply* mapfni (car mapx))) 
(COND 
(mape 
(RPLACD mape mapy) ) 
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(T 
(SETQ mapl 
| (SETQ mape mapy))))) 
(PROG NIL 
loop1i 
(COND 
((SETQ mapy (CDR mape)) 
(SETQ mape mapy) 
(GO loop1))))) 
(SETQ mapx 
(COND 
(mapfn2 
, (APPLY* mapfn2 mapx) ) 
T 
: (CDR mapx) ))) 
(GO loop) ) 
) 


All of the mapping functions discussed so far work only on lists as. their 
arguments. These functions return NIL if their argument is not a list. You may 
consider modifying the function definitions to make a list of the argument if it is 
not a list. To do so, in each function, you should replace the expression 


(COND 
((NLISTP mapx) 
(RETURN ...))) 


by the expression 


(COND 
((NLISTP mapx) 
(SETQ mapx (LIST mapx))) 


which makes the argument a list if it is not already one. 
You may want to define a new set of mapping functions which operate in this 
manner to complement the basic functions provided by INTERLISP. 


12.1.4 Mapping over Two Arguments 


As we have seen, the mapping functions described above accept only one argu- 
ment list to be operated upon. Many times you will want to apply a mapping 
function to two lists on an element-by-element basis. INTERLISP provides two 
functions MAP2C and MAP2CAR that allow you to accomplish this task. Their 
formats are 
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Function: MAP2C 
MAP2CAR 


# Arguments: 3-4 


Arguments: 1) MAPX, an argument list 
2) MAPY, an argument list 
3) MAPFN1, the function to be applied 
4) MAPFN2, the function used to compute 
successive tails of MAPX and MAPY 


Value: NIL if MAP2C; 
a list of results if MAP2CAR. 


MAP2C and MAP2CAR operate exactly like MAPC and MAPCAR. How- 
ever, MAPEN1 is applied to successive elements of MAPX and MAPY. That is, 
MAPEN1 is a function of at least two arguments. MAP2C (respectively MAP- 
2CAR) terminates whenever one of the two lists is exhausted; that is, when the 
result of MAPFN2 or CDR (the default) is NIL. 


«-(SETQ numbers-1 '(1 2 3 4)) 
(1 2 3 4) 


«(SETQ numbers-2 '(100 200 300 400)) 
(100 200 300 400) 


<-(MAP2CAR numbers-1 numbers-2 (FUNCTION IPLUS) ) 
(101 202 303 404) 


«-(MAP2CAR numbers-1 NIL (FUNCTION IPLUS)) 
NIL 


<(MAP2CAR numbers-2 numbers-2 (FUNCTION ITIMES) ) 
(10000 40000 90000 160000) 


A Definition for MAP2CAR 
We might define MAP2CAR as follows: 


(DEFINEQ 
(map2car (mapx mapy mapfni mapfn2) 
(PROG (map.list map.expression) 
(SETQ map.list NIL) 
loop 
(COND 
((OR 
(NLISTP mapx) 
(NLISTP mapy) ) 
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(* 
MAP2CAR works only with 
lists. 
) 
(RETURN map.1list) )) 
(SETQ map.expression 


(CONS 
(APPLY* mapfn1 
(CAR mapx) 
(CAR mapy) ) 
map.expression) ) 
(COND 
(map.list 
(SETQ mapx 
(APPLY* mapfn2 mapx) ) 
(SETQ mapy 
(APPLY* mapfn2 mapy)) ) 
T 
(SETQ mapy (CDR mapy)) 
(SETQ mapx (CDR mapx)))) 
(GO loop) ) 


)) 


12.1.5 Mapping Across Atoms: MAPATOMS 


In many applications you may want to apply a function to some set of atoms that 
have been created by your program. One way to do this is to build a list of all the 
atoms as they are created and apply a function to them using one of the mapping 
functions. If your application is very large, this may consume substantial space 
to keep track of all the atoms. 

MAPATOMS allows you to apply a function to all the literal atoms in the 
system. However, its major problem is that it uses both atoms defined or created 
by INTERLISP itself as well as all the atoms that you have created. In order to 
apply it to a specific subset of atoms, your function, which is passed as an argu- 
ment, must perform a filtering of all the atoms to select those to be operated 
upon. 

MAPATOMS takes the following format 


Function: MAPATOMS 
# Arguments: 1 
Argument: 1) a function to be applied, FN 


Value: NIL 
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The value of MAPATOMS is NIL so it is the responsibility of the function to 
generate a result that you may later utilize. If you want to print all of the atoms 
in the system (of which there are a great many!), you might use the following 
expression 


+-(MAPATOMS '(LAMBDA (x) (PRINT x))) 
f 

/SETPROPLIST 

FORKBLOCK 

DPROG 

CHANGEDFNSLST 

DUMPSTATCOMS 

DECLARE 

INTEGERLENGTH 

MERGEINSERT 


which are the first few atoms printed from an INTERLISP-10 system. 

Note that USERWORDS (see Section 22.7.2) is a list of all the atoms that 
you have entered via type-in. You may apply MAPATOMS to this list to operate 
only upon the atoms that you have created. Unlike other LISP dialects, such as 
FranzLisp or MACLisp, there is no function corresponding to (OBLIST) which 
returns a list of all atoms created by the user. 

You may print every atom with a function definition using the following ex- 
pression 


<(MAPATOMS '(LAMBDA (x) 

(COND 

((GETD x) (PRINT x))))) 

/SETPROPLIST 
FORKBLOCK 
DECLARE 
INTEGERLENGTH 
MERGEINSERT 


If you attach properties to each of the atoms that you create in your program 
describing the usage of the atom, then you may code a MAPATOMS expression 
to iterate over selected sets of atoms and perform some special operation on 
them. 


12.1.6 A Generic Printing Function 


INTERLISP provides MAPRINT as a general printing function. Even though it 
is an output function, we discuss it in this chapter because it operates as a map- 


ping function. 
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MAPRINT has the following format 


Function: MAPRINT 
# Arguments: 7 


Arguments: 1) an argument list, MAPX 
2) an output file, FILE 
3) a left expression demarcator, LEFT 
4) a right expression demarcator, RIGHT 
5) an expression separator, SEP 
6) a print function, PFN 
7) LISPXPRINTFLG 


Value: NIL 


MAPRINT applies PFN to successive elements of MAPX. PFN should be a 
printing function. If it is NIL, PRIN1 is assumed. The results produced by MA- 
PRINT are directed to FILE. If FILE is NIL, then T is assumed (i.e., the termi- 
nal although it may also be explicitly specified). 

You may use LEFT, RIGHT, and SEP to construct expression forms to suit 
your application. Before each expression result from applying PFN to an ele- 
ment of MAPX is printed, MAPRINT will print the value of LEFT. Similarly, 
after the expression is printed, MAPRINT will print the value of RIGHT. Indi- 
vidual expressions are separated by the value of SEP or “”’ (a string consisting of 
a single space) if SEP is NIL. 

To mimic the application of PRIN1 for lists, you could execute the following 
function call 


<(MAPRINT presidents NIL 4( %)) 
(tyler polk lincoln hayes)NIL 


at the terminal since the file specification is NIL. 


«<-(MAPRINT presidents NIL NIL NIL NIL 'PRINT) 
tyler 

polk 

lincoln 

hayes 

NIL 


«<-(MAPRINT presidents T NIL '%. '%,) 
tyler,polk,lincoln,hayes.NIL 


because it is using PRIN1 to print the output. We can modify this to place spaces 
between the entries and print NIL on the following line as follows 
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«-(MAPRINT presidents 
T 
NIL 
(CONCAT (MKSTRING (CHARACTER (CHARCODE CR))) 
' (MKSTRING (CHARACTER (CHARCODE LF) ))) 
! tt 
3 
tyler, polk, lincoln, hayes 
NIL 


If the LISPXPRINTFLG is T, then LISPXPRINI will be used in place of 
PRIN1 (see Section 15.1.1). 


12.2 APPLYING FUNCTIONS TO SUBSETS 


When we apply a mapping function to a list, we often want the result to reflect 
only the non-NIL values. In the generic mapping functions described in Section 
12.1, a NIL will be explicitly reflected in the resulting list of those functions 
returning a list. SUBSET, which returns only the non-NIL values, takes the 
form 


Function: SUBSET 
# Arguments: 2-3 


Arguments: 1) a list, MAPX 
2) a function, MAPFN1, to be applied to 
the successive subsets of MAPX 
3) a function, MAPFN2, to be used to 
compute the successive subsets of MAPX 


Value: A list of the non-NIL values resulting 
from applying MAPFN1 to MAPX. 


Consider the following example: 


«(SUBSET '(a 2 b 6 x 32 i v 14) (FUNCTION NUMBERP) ) 
(2 6 32 14) 


A Definition for SUBSET 
We might define SUBSET as follows: 


(DEFINEQ 
(subset (mapx mapfn1 mapfn2) 
(PROG (map.list map.expression) 
(SETQ map.list NIL) 
loop 
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(COND 
(( oe mapx) 
¥ 


SUBSET works only on lists. 


(RETURN map.1list)) 
((APPLY* mapfn1 (CAR mapx)) 
(* 


If the result is non-NIL, then 
CONS it to the list of results. 
(COND 
((NULL map.list) 
(SETQ map.list 
(SETQ map.expression 
, (CONS (CAR mapx))))) 
T 
(SETQ map.expression 
(CDR 
(RPLACD map.expression 
(RPLACD 
(CONS (CAR mapx) 
mapexp) ))))) 
))) 
(SETQ mapx 
(COND 
(mapfn2 
(APPLY* mapfn2 mapx) ) 
(T (CDR mapx)))) 
" (GO loop) ) 


SUBSET returns a list that contains only the non-NIL values produced by 
applying a function to successive elements of a list. SUBSET has the same for- 
mat as MAPCAR. Unlike MAPCAR, however, NIL values produced when 
MAPEN1 is applied to MAPX are ignored in constructing the resulting list. 





12.3 SPECIFYING AN ARGUMENT AS A FUNCTION: 
FUNCTION 


In many applications we want to pass the name of a function as an argument to 
another function. INTERLISP provides the FUNCTION function, to assist us. 
FUNCTION is an NLAMBDA function that does not evaluate its arguments. It 
has the following format 
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Function: FUNCTION 
# Arguments: 2 
Arguments: 1) a function name or definition, FN 
2) an environment specification, 
ENVIRONMENT 
Value: Either the function name or a FUNARG 
specification. 


If the environment specification is NIL, then FUNCTION operates exactly 
like QUOTE by returning the function name or definition. For example, 


+«-(MAPCAR presidents (FUNCTION PRINT) ) 
tyler 

polk 

lincoln 

hayes 

NIL 


yields the same results as 


«-(MAPCAR presidents 'PRINT) 
tyler 

polk 

lincoln 

hayes 

NIL 


Note: the difference in the two forms is that when the expression is compiled 
(see Chapter 31), code will be produced for the first form above while in the 
second it will not. This is particularly important when the argument to FUNC- 
TION is a LAMBDA expression. In this case, the compiler will define and com- 
pile an auxiliary function for the LAMBDA expression, whereas if the 
LAMBDA expression is the argument of QUOTE, it will not. Thus, it is good 
programming practice to always specify functions passed as arguments using the 
FUNCTION mechanism to ensure that the program operates properly in both 
compiled and interpreted modes. 

If the environment specification is not NIL, it may be a list of variables that 
are used freely by the function specified. By free variables, we mean those vari- 
ables that are globally accessed by the function but which are not specified in the 
function’s parameter list. In this case, FUNCTION returns a FUNARG specifi- 
cation (see Section 12.4) which defines the stack frame where the values of the 
variables specified in the environment are bound. 
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If ENVIRONMENT is an atom, it is evaluated and its value is used as a list 
of free variables. 


ENVIRONMENT may also be a stack pointer (see Chapter 30) which points 
to a stack frame containing bindings for the variables used by by FN. 


12.4 THE FUNARG MECHANISM 


When FUNCTION is given an environment specification, INTERLISP must 
know where the values of the variables are to be found before it can execute the 
function. To do so, it constructs a FUNARG expression that has the form 


(FUNARG function stack-position) 


where STACK-POSITION is a pointer to a stack frame (see Chapter 30) that 
contains the bindings of the variables specified in the environment. 

FUNARG is not a function, but like LAMBDA and NLAMBDA, it has a 
special meaning that is recognized by INTERLISP when applying a function toa 
set of arguments. The virtue of the FUNARG mechanism is that it allows the 
user to define the environment in which the variables are bound rather than 
INTERLISP itself (which always uses the most recent stack frame). 

The FUNARG mechanism is an advanced feature of INTERLISP that re- 
quires considerable caution in its usage. You probably should read and under- 
stand Chapter 30 concerning the stack before you attempt to use FUNARGs 
directly. 


12.4.1 Using FUNARGs 


Suppose that you have a function that you would like to apply to an argument 
and also apply to its result. The IRM [irm83] suggests an example (after which 
the following is modeled) 2 


<— (DEFINEQ 
(reapply (fn value) 
(APPLY* fn (APPLY* fn value) ) 
)) 


(reapply) 


REAPPLY applies FN to VALUE, and then applies FN to the result. That 
is, it computes the composition of a function with itself (in mathematical terms). 
Consider the example 


«(REAPPLY (FUNCTION (LAMBDA (X) (ITIMES X X))) 5) 
625 
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Let us trace this activiy to see what happens (tracing is defined in Section 
20.1): 


«(TRACE ITIMES) 
(ITIMES) 


«(REAPPLY (FUNCTION (LAMBDA (X) (ITIMES X X))) 5) 
ITIMES: 


¥ARGI¥ = 5 
¥ARG2* = 5 
U=2 

ITIMES = 25 
ITIMES: 
¥ARGI*¥ = 25 
¥ARG2* = 25 
U=2 

ITIMES = 625 
625 


which is the answer we expect. However, suppose we execute the following ex- 
pression 


<(SETQ value 10) 
10 


«(REAPPLY (FUNCTION (LAMBDA (X) (ITIMES X VALUE))) 5) 
ITIMES: 


¥ARGIX = 5 
¥ARG2* = 5 
U=2 

ITIMES = 25 
ITIMES: 
¥ARG1 = 25 
¥ARG2* = 5 
U = 2 

ITIMES = 125 
125 


which is not what we expect to see! This should multiply the value of the global 
variable VALUE by the argument to the LAMBDA expression. The problem is 
that the LAMBDA expression is treated like an EXPR. VALUE is bound within 
the context of REAPPLY to its second argument. The solution (as noted by the 
IRM) is to pass the value of VALUE as an environment for the EXPR. This 
expression would take the form 
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<— (REAPPLY 

(FUNCTION (LAMBDA (X) (ITIMES X VALUE)) 
(VALUE) ) 

5) 

ITIMES: 

*ARGI* = 5 

*ARG2* = 10 

U=2 

. ITIMES = 50 

ITIMES: 

*ARG1* = 50 

*¥ARG2* = 10 

U=2 

ITIMES = 500 

500 


which is the correct answer. Note that VALUE now has the correct binding (i.e., 
10) because the second argument to FUNCTION specifies an environment in 
which its value is accessible. 

As the IRM notes [irm83], this example is somewhat contrived to force the 
problem to be demonstrated—namely, the clashing of variable names. Of 
course, we could fix the problem by changing the names of the arguments so that 
they don’t conflict. However, in large systems with hundreds of functions, you 
may not notice problems of this sort until the functions are strongly embedded in 
the system. It may not be feasible to edit all of the functions to change argument 
names (even with Masterscope). The method described above provides a fix that 
allows you to continue working until you are ready to rewrite the affected por- 
tions of the system. 


12.4.2 Constructing FUNARGs to be Passed as Functions 


The IRM notes that you may also construct a FUNARG which may be passed to 
different functions for application. The FUNARG resides on the stack, and so 
consumes no permanent storage. Consider the following example (after [irm83]: 


< (DEFINEQ 
(make.counter (count) 
(FUNCTION 
(LAMBDA NIL 
(PROG1 count 
(SETQ count (ADD1 count) ))) 

(count) ) 

)) 


(make. counter) 
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«-(SETQ counter-1 (MAKE.COUNTER 1)) 

(FUNARG (LAMBDA NIL (PROG1 COUNT (SETQ COUNT (ADD1 
COUNT) ) ) ) 

[STACKP]#152733/FUNARG) 


So, MAKE.COUNTER returns a FUNARG that increments the counter 
and returns the previous value of the counter. Each call to MAKE.COUNTER 
creates a new FUNARG expression with a new, independent environment. 
Thus, multiple counters may be generated and used throughout a program. 

Now, to apply the FUNARG, we can execute the expression 


“(APPLY counter-1) 


1 
<-REDO "this is a Programmer's Assistant 
2 command (see Chapter 25)" 


Note that the counter’s previous value is maintained in the stack frame, so 
that each successive application of the counter produces the correct value. 
Let us create a second counter, which is initialized to count from 100: 


<(SETQ counter-2 (MAKE.COUNTER 100)) 

(FUNARG (LAMBDA NIL (PROG1 COUNT (SETQ COUNT (ADD1 
COUNT) ) ) ) 

[STACKP]#152732/FUNARG) 


This is an independent environment (note change in stack address). Now, 
let us apply our new counter: 


“(APPLY counter-2) 
100 


REDO 
101 


and, for good measure, let us check to see that COUNTER-1 is independent: 


«(APPLY counter-1) 
3 


Thus, by using a FUNARG expression, you can create a function object 
(something that acts like a function, looks like a function, but is not a function) 
which has updatable bindings and which maintains the value of those bindings 
between calls to the function object. The bindings are only accessible through an 
instance of that function object (i.e., when you actually execute the function 
object) 
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“count 
UNBOUND ATOM 
COUNT 


You may want to compare and contrast this mechanism with the notion of 
generators which was introduced in Section 8.11. 


12.5 APPLYING A FUNCTION TO ITS ARGUMENTS 


When we pass a function name as an argument, it is usually accompanied by a 
list of variables that it will operate on. The function, however, expects its argu- 
ments to be enumerated such that there is one-to-one correspondence between 
the arguments and the parameters. For example, suppose we have a list of num- 
bers that we want to add together: 


<(SETQ numbers '(10 23 35 46)) 
(10 23 35 46) 


We cannot say (PLUS numbers) because PLUS expects a set of individual 
numbers to work with, e.g., 


«(PLUS 10 23 35 46) 
114 


Thus, (PLUS numbers) would result in an error because the argument is not 
an atom. PLUS does not know how to decompose a list of numbers into the 
individual numbers that it will compute with. We, of course, could enumerate 
the list, e.g., (PLUS (CAR numbers) (CADR numbers) (CADDR numbers) 
(CADDDR numbers)), but this is both tedious and quickly runs into problems if 
the list is longer than four items. 

INTERLISP provides the function APPLY to deal with this problem (so that 
we do not have to do the enumeration!). Its format is 


Function: APPLY 


# Arguments: 2 


Arguments: 1) a function 
2) a list of arguments 


Value: The value of the function operating upon 
the argument list 


Thus, we can say 


«(APPLY 'PLUS numbers) 
114 
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or better yet 


«(APPLY (FUNCTION PLUS) numbers) 
114 


APPLY performs the appropriate interfacing between the function and the 
list of arguments that we would like it to operate upon. 

APPLY does not evaluate the elements of the argument list. However, the 
arguments given to APPLY are evaluated because it is a LAMBDA function. 
The function is responsible for evaluating the arguments that appear in the ar- 
gument list. For example, 


«(APPLY (FUNCTION SETQ) 
"(FOO (ADD1 3))) 
4 


which sets FOO to 4, but 


“(APPLY (FUNCTION SET) 
'(FOO (ADD1 3))) 
(ADD1 3) 


will set FOO to (ADD1 3). 
An alternative form, APPLY*, collects an indefinite number of arguments 
(2-N) into a list so that the function may operate upon them. For example, 


<(APPLY* (FUNCTION PLUS) 10 23 35 46) 
114 


which is equivalent to 


(APPLY (FUNCTION PLUS) 
(LIST 10 23 35 46)) — 114 


APPLY and APPLY* have also been described in more detail in Chapter 8 
because they are actually functional forms. Please consult Section 8.9 for addi- 


tional information. 


12.5.1 Determining S-expression Depth 


As we have seen, S-expressions may be complex structures. Suppose that we 
wanted to know the depth of an S-expression, e.g., the level of the deepest sublist 
of the given S-expression. We might define a function DEPTH that calculates 


the depth as follows: 
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+ (DEFINEQ 
(depth (s-expression) 
(COND 
((NULL s-expression) 1) 
((ATOM s-expression) 0) 
(T 
(ADD1 
(APPLY (FUNCTION MAX) 
(MAPCAR s-expression 
'DEPTH) ) ) )) 
)) 


DEPTH returns 1 if the S+expression is NIL because we treat NIL as the 
empty list. It returns 0 if the S-expression is an atom because it is not a list at all. 
Otherwise, we apply DEPTH recursively to all of the elements of the S-expres- 
sion. 





13 





Arithmetic Functions 


As we noted in Chapter 2, there are three different types of numbers in IN- 
TERLISP: small and large integers, and floating point numbers. The minimum 
and maximum values are stored in system variables. For INTERLISP-D, the 
following ranges are observed 


small integers MIN.SMALLP -65536 
MAX .SMALLP 65535 

large integers MIN. FIXP -2147483648 
MAX. FIXP 2147483647 

floating point MIN. FLOAT -3.402823 E38 
MAX. FLOAT 3.402823 E38 


INTERLISP-10 (version dated 26-SEP-83) does not have these system vari- 
ables defined as of this writing. 

INTERLISP/370 maintains the same values for large integers and floating 
point numbers, but treats small integers as 24-bit quantities. Thus, the range for 
small integers in INTERLISP/370 is [-2**24,2**24]. 

A small integer is one which satisfies the predicate SMALLP, but it is also 
an integer which may be stored in the pointer field of a word. 

Large integers or floating point numbers are stored as full word quantities. 
To distinguish these numbers from other INTERLISP pointers, INTERLISP 
“‘boxes’”’ the number. That is, when a large integer or floating point number is 
created either by an arithmetic operation or via READ, it is stored into a full 
word. A pointer to that word is passed around among functions rather than the 
actual numeric quantity itself. We say that the number has been boxed. When 
some arithmetic function requires the actual “‘value,’’ the converse function of 
unboxing, i.e., performing the extra level of addressing, retrieves the number. 
Boxing consumes two words of storage for each number that is created: one for 
the number and one for the pointer. Unboxing requires no additional storage. 
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13.1 INTEGER FUNCTIONS 


INTERLISP provides the standard arithmetic functions for computing on inte- 
gers, both small and large. Integer functions work only on integers. If they are 
given a floating point number, it is first truncated to form the corresponding 
integer and then used in the computation. If an integer function is given a non- 
numeric argument, it will display an error message: NON-NUMERIC ARG. 


13.1.1 Integer Addition 


You can add two or more integers using IPLUS. It takes the form 


Function: IPLUS 
# Arguments: 1-N 


Arguments: 1) a number, X1 
2) a number, X2 
3-N) numbers, X3 ... XN 


Value: The integer sum of the numbers Xi. 


IPLUS is a nospread function, meaning it may take an indefinite number of 
arguments. Consider the following examples: 


<—(SETQ number-of-oranges 10) 
10 
<-(SETQ number-of-apples 20) 
20 


where the numbers are treated as literal atoms (as described in Chapter 2). We 
can then add the number of apples and oranges by 


«(IPLUS number-of-apples number-of-oranges) 
30 


IPLUS is commutative, so we can reverse the order of the arguments and 
obtain the same answer 


«(IPLUS number-of-oranges number-of-apples) 
30 


IPLUS treats NIL as zero. Thus, we can use either of the following forms 


+ ( IPLUS) 
0 
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+-(IPLUS 5 10 NIL 15 20 NIL) 
50 


where the last example demonstrates that IPLUS may take multiple arguments. 


Adding One to a Number 
An alternative function, ADD1, provides for the very common operation of add- 
ing one to a number. It takes the form 


Function: ADD1 

# Arguments: 1 

Argument: 1) a number, X1 

Value: The number plus 1 as an integer. 


Consider the example 


<-(ADD1 number-of-oranges) 
21 


A Definition for ADD1 
We might define ADD1 as follows: 


(DEFINEQ 
(addi (x) 
(IPLUS x 1) 
)) 


13.1.2 Integer Subtraction 


Integer subtraction is provided by the IDIFFERENCE, which subtracts its sec- 
ond argument from its first argument. It takes the form 


Function: IDIFFERENCE 

# Arguments: 2 

Arguments: 1) a number, X1 
2) a number, X2 

Value: The difference between X1 and X2 as an 
integer. 


Consider the following examples: 


«-(IDIFFERENCE number-of-oranges number-of-apples) 
10 
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+ (IDIFFERENCE) 
"Non-Numeric Arg" 


«-(IDIFFERENCE number-of-apples number-of-oranges) 
-10 


Note that IDIFFERENCE is not a commutative function; that is, the order 
of the arguments matters in computing the result. 





- A Definition for IDIFFERENCE 
We might define IDIFFERENCE as follows: 


(DEFINEQ 
(idifference (x y 
(IPLUS x (IMINUS y)) 
)) 


Subtracting One from a Number 
A special function is provided for the common operation of subtracting one from 
a number, SUB1. It takes the form 


Function: SUB1 

# Arguments: 1 

Argument: 1) a number, X1 

Value: The value of X1 minus 1 as an integer. 


Consider this example: 


<(SUB1 number-of-apples) 
9 


A Definition for SUB1 
We can define SUB1 in terms of IDIFFERENCE as follows: 


(DEFINEQ 
(SUB1 (a-number) 
(COND 
((NUMBERP a-number) 
(IDIFFERENCE a-number 1) ) 
(T 
(ERROR "Non-numeric Argument'') ) ) 
)) 


or, alternatively, 
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(DEFINEQ 
(subi (x) 
& (IPLUS x -1) 


Negating a Number 

Negation of a number is often treated as the subtraction of that number from 
zero. INTERLISP provides the IMINUS function to negate a number. It takes 
the form 


Function: IMINUS 

# Arguments: 1 

Argument: 1) a number, X1 

Value: The negative value of the number. 


Consider the example 


<(IMINUS number-of-oranges) 
-20 


A Definition for IMINUS 
We might define IMINUS as follows: 


(DEFINEQ 
(iminus (x) 
(IDIFFERENCE 0 x) 
)) 


The foregoing examples demonstrate that an INTERLISP kernel actually 
needs very few primitive arithmetic functions. From these few primitives, all 
other arithmetic functions may be constructed. Selection of the few primitives 
should be based on the efficiencies found in the underlying machine architec- 
ture. 


13.1.3 Integer Multiplication 


Integer multiplication is performed by the ITIMES. It takes an indefinite num- 
ber of arguments just as IPLUS does. It takes the form 


Function: ITIMES 
# Arguments: 1-N 
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Arguments: 1) a number, X1 
2) a number, X2 
3-N) numbers, X3 ... XN 


Value: The cumulative product of the numbers Xi. 
ITIMES is a nospread function. Consider the following examples: 


«-(ITIMES number-of-apples number-of-oranges) 
200 

<—(ITIMES) 

uf 


because ITIMES assumes that NIL is treated as 1. 


13.1.4 Integer Division 


Integer division is provided through two functions: IQUOTIENT and IRE- 
MAINDER. They take the form 


Function: IQUOTIENT 
IREMAINDER 

# Arguments: 2 

Arguments: 1) a number, X1 
2) a number, X2 

Value: The quotient or remainder of X1 and X2, 
respectively. 


Given two numbers, IQUOTIENT produces their truncated quotient. For 
example, 


«(IQUOTIENT number-of-oranges number-of-apples) 
2 
<(IQUOTIENT number-of-apples number-of-oranges) 
0 

because IQUOTIENT is not commutative. 


< ( IQUOTIENT) 
"Non-Numeric Arg'"' 
NIL 


Meanwhile, IREMAINDER produces the remainder when the first argu- 
ment is divided by the second. For example, 





13.1 Integer Functions 357 


< (IREMAINDER number-of-oranges number-of-apples) 
0 


+-(IREMAINDER number-of-apples number-of-oranges) 
10 


 ( IREMAINDER) 
"Non-Numeric Arg" 
NIL 


Dividing a Number by Two 

A frequent arithmetic operation that is performed is to divide a number by two. 
You might define a function called HALF that returns the integer closest to the 
quotient of the argument and 2: 


(DEFINEQ 
(ihalf (x) 
(IQUOTIENT x 2) 
)) 


13.1.5 Minimum and Maximum 


INTERLISP provides functions for finding the minimum and maximum of a 
sequence of integers. These are the IMIN and IMAX functions, respectively. 
They take the form 


Function: IMIN 
IMAX 
# Arguments: 1-N 


Arguments: 1) a number, X1 
2) a number, X2 
3-N) numbers, X3 ... XN 


Value: The minimum or maximum number, 
respectively, of the numbers Xi as an 
integer. 


IMIN and IMAX are nospread functions. Consider the following examples: 


«(IMIN 7 32 -1 3 568 91) 
-1 
+(IMAX 7 32 -1 3 568 91) 
568 


Note that (IMIN) will return the value of the smallest possible integer and 
(IMAX) will return the value of the largest possible integer. 


358 Arithmetic Functions 


+ (IMIN) 
-2147483648 


+ (IMAX) 
2147483647 


13.1.6 Integer Modulus 


You may compute the integer modulus using IMOD, which takes the form 


Function: IMOD 
# Arguments: 2 
Arguments: 1) a number, X1 
2) a number, X2 
Value: The integer modulus of X1 and X2. 


The integer modulus differs from the value of IREMAINDER in that it al- 
ways produces a non-negative integer in the range [0...X2]. For example, 


+-(IMOD 42 12) 
6 


<(IMOD 128 365) 
128 


<(IMOD) 
"non-numeric arg"! 
NIL 


+-(IMOD 786 -34) 
4 


13.1.7 Converting to an Integer 


You may convert a number of unspecified type to an integer using FIX, which 
takes the form 


Function: FIX 

# Arguments: 1 

Argument: 1) a number, X 
Value: An integer. 


FIX returns X if it is an integer. Otherwise, it converts X to an integer by 
truncating the fractional bits of X. Consider the examples 
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«(FIX 10) 
10 ? 


This example causes problems because FIX is also a command to the Pro- 
grammer’s Assistant (see Chapter 25). To properly use FIX from the top level, 
you must assign its result to a variable. 


+ (SETQ x (FIX 1053.456)) 
1053 


(SETQ x (FIX)) 
"non-numeric arg"! 
NIL 


13.2 INTEGER PREDICATES 


INTERLISP provides a variety of predicates for comparing integers, testing 
their values and their characteristics. 


13.2.1 Boolean Predicates 


INTERLISP provides four Boolean predicates for comparing the values of two 
integers. They take the form 


Function: IGREATERP 
ILESSP 
IGEQ 
ILEQ 
# Arguments: 2 
Arguments: 1) a number, X1 
2) a number, X2 
Value: T, if X1 <relation) X2; otherwise, NIL. 


The Boolean predicates are defined for two integers [x] and [y] as follows: 


Predicate Definition 

IGREATERP t if [s].>--fy] 
NIL otherwise 

ILESSP T if [x] ¢ [y] 


NIL otherwise 
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IGEQ T if [x] =) [y] 
NIL otherwise 
ILEQ T if [x] <= [yl] 


NIL otherwise 
Consider the following examples: 
(IGREATERP 75.0 123.4) 
NIL 
<—(ILEQ 24 56) 
T 


If either or both of X1 and X2 is NIL, these Boolean predicates generate an 
error message ““NON-NUMERIC ARG” and return NIL. 


13.2.2 Predicates for Testing Equality 


INTERLISP provides several predicates for testing for the equality of two inte- 
gers, or for testing the equality of an integer to an implied value. 
To test if two integers are equal, you should use IEQP. It takes the form 


Function: IEQP 
# Arguments: 2 


Arguments: 1) a number, X1 
2) a number, X2 


Value: T, if X1 is equal to X2; otherwise, NIL. 


IEQP compares the values of the two integers regardless of whether they are 
large or small. For examples, 


<(SETQ number-of-hands 2) 


2 

<(SETQ number-of-legs 2) 

2 

«-(IEQP number-of-hands number-of-legs) 
t 


Note that NUMBER-OF-HANDS and NUMBER-OF-LEGS are both small 
integers. It is suggested in the IRM [irm83] that you can use EQ if the two argu- 
ments are known to be small integers. That is because some implementations of 
INTERLISP perform a special allocation of small integers to a unique area of 
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INTERLISP’s address space. For reasons of program portability, I suggest that 
you use the general form, IEQP, which is guaranteed to operate correctly for all 
implementations even though it may take slightly longer to execute. 

A common arithmetic test that is often performed is to test for the equality 


of an integer to zero. INTERLISP provides the predicate ZEROP to perform this 
test. It takes the form 


Function: ZEROP 

# Arguments: 1 

Argument: 1) a number, X1 

Value: T, if X1 is zero; otherwise, NIL. 


A Definition for ZEROP 
We might define ZEROP as follows: 


(DEFINEQ 
(zerop (x) 
(IEQP x 0) 
)) 


Testing for Equality to One 

Some implementations of LISP also provide a predicate for testing the equality 
of an integer to the number 1. Strangely, INTERLISP does not contain such a 
function. We can easily define such a predicate as follows: 


(DEFINEQ 
(ONEP (an-integer) 
(COND 
((NUMBERP an-integer) 
(COND 
((FIXP an-integer) 
(IEQP an-integer 1))) 
(T 
(ERROR '"Non-numeric Argument’) ) ) 
)) 


Testing for the Maximum or Minimum Integer 
You may also wish to test whether or not a variable has the value of the maxi- 
mum or minimum integer. We might define these functions as follows: 


(DEFINEQ 
(maxp (x) 
(IEQP x MAX.FIXP) 
)) 
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(DEFINEQ 
(minp (x) 
o (IEQP x (MIN.FIXP) 


13.2.3 Predicates for Testing Characteristics 


INTERLISP provides a number of predicates for testing the characteristics of 
integers. j 


Testing For a Negative or Positive Number 

We often want to know whether or not an integer is negative. Using ILESSP, we 
have to evaluate the integer with respect to zero as the second argument. Because 
this test is so common, INTERLISP provides us with a “hardwired” predicate, 
’ MINUSP, which takes the form 


Function: MINUSP 
PLUSP 
# Arguments: 1 
Argument: 1) a number, X 
Value: T, if X is negative (i.e., less than 0). 


MINUSP returns T if its argument X is less than zero, and NIL otherwise. 
INTERLISP does not provide a corresponding predicate for testing if the value 
of an integer is positive. However, we can easily define such a predicate as fol- 
lows: 


(DEFINEQ 
(PLUSP (an-integer) 
(COND 
((NUMBERP an-integer) 
(COND 
((FIXP an-integer) 
(IGREATERP an-integer 0)))) 
(T 
(ERROR '"'Non-numeric Argument'') ) ) 
)) 


Testing for a Small Integer 
INTERLISP provides a function for testing whether or not an integer is a small 
integer as described above. This predicate is called SMALLP, which takes the 


form 
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Function: SMALLP 

# Arguments: 1 

Arguments: 1) a number, X 

Value: T, if X is a small integer. 


It returns T if its argument lies within the range of small integers for the 
particular implementation of INTERLISP; otherwise, it returns NIL. The ra- 
tionale for using small integers (and their special allocation procedures) derived 
from early implementations of INTERLISP where storage was often limited. 
More recent implementations use a virtual storage management procedure 
which, I believe, obviates the need for even considering whether or not an integer 
is small. Therefore, I suggest that the use of SMALLP be foregone. 


Testing for an Integer 
INTERLISP provides a predicate for determining whether or not its argument is 
an integer. This function is called FIXP and it takes the form 


Function: FIXP 

# Arguments: 1 

Arguments: 1) a number, X 

Value: X, if X is an integer (large or small). 


Unlike the other integer predicates, FIXP returns the number X if its argu- 
ment is an integer, but NIL otherwise. It does not generate an error if its argu- 
ment is non-numeric. 


<— (FIXP) 
NIL 


A Definition for FIXP 
We might define FIXP as follows: 


(DEFINEQ 
(fixp (number) 
(AND (NUMBERP number) 
(NOT (FLOATP number) ) 
number) 


)) 


Testing for Even or Odd Integers 
INTERLISP provides functions for testing whether an integer is even or odd. 


They take the form 
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Function: ©  EVENP 
ODDP 
# Arguments: 2 
Arguments: 1) a number, X1 
: 2) a number, X2 
Value: T, if the result is even or odd, 
respectively. 


EVENP and ODDP are nospread functions. If X2 is not given, EVENP is 
equivalent to 


(ZEROP (IMOD Xi 2)) 
otherwise, it is equivalent to 

(ZEROP (IMOD X1 X2)) 

Consider the following examples: 


«—(EVENP 15378) 
a 
<—(ODDP 187237) 
T 


+ (EVENP) 
t 


+ (ODDP) 
NIL 


<(EVENP 24 4) 
T 


+ (EVENP 128 6) 
NIL 


<(EVENP 128 -4) 
T 


Note that NIL is treated the same as 0. These examples, taken from a DEC- 
System-20, show that the system treats 0 as an even number. Caution should be 
exercised as the notion of even and odd for zero is machine-dependent. 


A Definition for EVENP and ODDP 
We might define EVENP as follows: 
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(DEFINEQ 
(evenp (x) 
,) (ZEROP (IMOD x 2)) 


and ODDP naturally follows as 


(DEFINEQ 
(oddp (x) 
(NOT (EVENP x)) 
)) 


Testing for a Power of Two 
POWEROFTWOP tests if its argument is a power of two. It takes the form 
Function: POWEROFTWOP 
# Arguments: 1 
Argument: 1) a number, X 
Value: T, if X is equivalent to two raised to a 
power. 
Consider the following examples: 
<-(POWEROFTWOP 1024) 
T 


«-(POWEROFTWOP 103678) 
NIL 


«- (POWEROF TWOP ) 
NON-NUMERIC ARG 
NIL 


«-(POWEROFTWOP 0) 
NIL 


«<(POWEROFTWOP 1) 
T 


13.3 MANIPULATING INTEGERS 


INTERLISP provides several functions that manipulate the values of integer ar- 
guments. These functions appear to correspond to instructions that were preva- 
lent in early computers where ‘‘bit twiddling” was a major concern of the pro- 
grammer. 
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13.3.1 Logical Manipulations 


INTERLISP provides three functions that perform logical functions on integers 
as bit representations. They take the form 


Function: LOGAND 
LOGOR 
LOGXOR 


# Arguments: 1-N 


Arguments: 1) a number, X1 
2) a number, X2 
3-N) numbers, X3 ... XN 


Value: The bitwise logical operation of the Xi as 
an integer. 


LOGAND, LOGOR, and LOGXOR are nospread functions. The logical 
operators are defined by the following table: 


Function Definition 

LOGAND [x1] and [x2] and .... 
LOGOR [xi} or [<2] OF sss 
LOGXOR [x1] xor [x2] Xor s... 


The value returned by each of these functions is an integer that represents 
the application of the function to its arguments. For example, if we define the 
following integers according to their bit representations 


27 11011 

6 00110 
13 01101 
10 01010 


we obtain the following results: 


+(LOGAND 27 10) 
10 


+(LOGAND 6 13) 
4 


«-(LOGOR 27 13) 
31 
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<(LOGOR 10 27) 
27 


-(LOGXOR 27 13) 
22 


It seems to me that considering the values of integers as particular bit pat- 
terns defeats the purpose for which INTERLISP was developed. These functions 
appear to be historical artifacts that remain from the days of limited memory. 

However, as with conventional programming languages, an argument can 
be made for the need to manipulate the bits within a word (see bit manipulations 
below). The problem is that attempting to port an INTERLISP program to a 
machine with a different word size can be very difficult. As a matter of philoso- 
phy, I suggest that you avoid bit manipulation functions unless absolutely neces- 
sary. 


Logical Negation 
INTERLISP-D implements an additional logical operation, LOGNOT, which 
takes the form 


Function: LOGNOT 

# Arguments: 1 

Argument: 1) a number, X 

Value: The logical negation of X. 


Consider the following examples: 


<-(LOGNOT 27) 
-28 


<-(LOGNOT 0) 
-1 


A Definition for LOGNOT 
We might define LOGNOT as follows: 


(DEFINEQ 
(lognot (x) 
(LOGXOR x -1) 
)) 


13.3.2 Integer Shift Functions 


INTERLISP provides several functions for shifting, both logically and arithmet- 
ically, the values of integers when they are treated as bit streams. The general 
format is ; 
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Function: LSH 
RSH 
LLSH 
LRSH 
# Arguments: 2 
Arguments: 1) a number, X 
2) the number of bits to shift, N 
Value: An integer resulting from bit shift, 


either arithmetic or logical. 


The arithmetic and logical shift functions are defined as follows 


LSH Arithmetic Left Shift 
RSH Arithmetic Right Shift 
LLSH Logical Left Shift 
LRSH Logical Right Shift 


Consider the following examples: 


<(SETQ a-number 32767) 


32767 

<-(LSH a-number 2) 
131068 

<-(LLSH a-number 2) 
131068 

<-(RSH a-number 8) 
127 

<—(SETQ a-number -127) 
-127 

«(RSH a-number 2) 
<3 

«-(LRSH a-number 2) 
1073741792 


Note that the last example produces a positive number because a logical 
right shift introduces zeroes in the high order bits. 

The basic difference between the logical and arithmetic shift functions lies 
in their treatment of the sign bit associated with the integer value. For arithmetic 
right shifts of negative numbers, the sign bit is propagated to each bit location to 
ensure that the result is a negative number. For logical right shifts, zeroes are 
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propagated. Logical and arithmetic left shifts always propagate zeroes from the 
right. 


13.3.3 Integer Conversion 


INTERLISP provides a function for creating an integer from a floating point 
number, FIX. FIX converts a floating point number to an integer by truncating 
any fractional bits and generating a new cell with the proper representation. If 
the given number is already an integer, INTERLISP merely returns the integer 
value without consuming any additional storage. 

The generic format for this function is 


Function: FIX 
# Arguments: 1 


Argument: a number 


Value: The integer value of the number. 


Consider the following example: 


«(FIX 1.2578) 
1.2578 ? 


<—(SETQ y (FIX 1.2578)) 
s | 


The reason that INTERLISP complains is that FIX is also a command rec- 
ognized by the Programmer’s Assistant. The Programmer’s Assistant intercepts 
type-in via LISPXREAD (see Section 25.1) so that you cannot type FIX directly 
to the toplevel of INTERLISP. 


13.3.4 The Greatest Common Divisor 


INTERLISP provides a function, GCD, for calculating the greatest common di- 
visor of two integers. Its generic format is 


Function: GCD 
# Arguments: 2 


Arguments: 1) a number, X 
2) a number, Y 


Value: The greatest common divisor of the two 
numbers. 
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Consider the following example: 


«(GCD 12468 3256) 
4 


“(GCD 43.54 12.78) 
1 


_Note that GCD accepts any two numbers and attempts to find their greatest 
common divisor. However, this function makes little sense when applied to float- 
ing point numbers. 


13.4 FLOATING POINT FUNCTIONS 


As with integers, INTERLISP also provides functions for operating upon float- 
ing point numbers. These functions, when given an integer, convert the integer 
to a floating point number internally before operating upon it. As with integers, 
when these functions are given a non-numeric argument, they respond with an 
error message “‘Non-numeric Arg” 


13.4.1 Floating Point Addition 
You may add two or more floating point numbers using FPLUS, which takes the 
form 

Function: FPLUS 

# Arguments: 1-N 


Arguments: 1) a number, X1 
2) a number, X2 
3-N) numbers, X3 ... Xn 


Value: The cumulative sum of the numbers Xi as a 
floating point number. 

FPLUS is a nospread function. Consider the following examples: 

<(FPLUS 34.6 123.5 -43.2) 

114.9 


 (FPLUS) 
0.0 


Adding One to a Number 
There is no corresponding floating point function to ADD1 in INTERLISP, but 
we can easily define one as follows: 





(DEFINEQ 


(fadd1 (x) 
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(FPLUS x 1.0) 


)) 


13.4.2 Floating Point Subtraction 


You may compute the difference between two floating point numbers using 
FDIFFERENCE, which takes the form 


Function: 
# Arguments: 
Arguments: 


Value: 


FDIFFERENCE 
2 


1) a number, X1 
2) a number, X2 


The difference between X1 and X2 as a 
floating point number. 


Consider the following examples: 


«+ (FDIFFERENCE 123.7 98.4) 


24.6 


 (FDIFFERENCE) 


NON-NUMERIC ARG 


NIL 


Subtracting One from a Number 
There is no corresponding floating point function to SUB1 in INTERLISP, but 
we may easily define one as follows 


(DEFINEQ 


(fsub1 (x) 


(FDIFFERENCE x 1.0) 


)) 


Floating Point Negation 
You may also compute the negative value of a floating point number (equivalent 
to subtracting it from zero) using FMINUS, which takes the form 


Function: 
# Arguments: 
Argument: 


Value: 


FMINUS 
pi 
1) a number, X 


The negative value of X as a floating 
point number. 
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Consider the following examples: 


+-(FMINUS 23.6) 
-23.6 


13.4.3 Floating Point Multiplication 
You may multiply two or more floating point numbers together using FTIMES, 
which takes the form 

Function: FTIMES 

# Arguments: 2-N 


Arguments: 1) a number, X1 
2) a number, X2 
3-N) numbers, X3 ... xN 


- Value: The cumulative product of the numbers Xi 
as a floating point number. 
FTIMES is a nospread function. Consider the following examples: 
«(FTIMES 103.5 12) 
1242.0 


< (FTIMES) 
0.0 


<(FTIMES 20.3 12.7 0.034) 
8.76554 


13.4.4 Floating Point Division 
INTERLISP provides two functions to support floating point division: FQUO- 
TIENT and FREMAINDER, which take the form 
Function: FQUOTIENT 
FREMAINDER 
# Arguments: 2 


Arguments: 1) a number, X1 
2) a number, X2 


Value: The quotient or remainder, respectively, 
of X1 and X2 as a floating point number. 


Consider the following examples: 
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+ (FQUOTIENT 196.74 23.54) 
8.357689 


+ (FREMAINDER 196.74 23.54) 
8.42 


< (FQUOTIENT) 
"non-numeric arg" 
NIL 


A Definition for FREMAINDER 
We might define FREMAINDER as follows: 


(DEFINEQ 
(fremainder (x1 x2) 
(FDIFFERENCE x1 
(FTIMES x2 
(FIX (FQUOTIENT x1 x2)))) 
)) 


13.4.5 Testing Equality of Floating Point Numbers 


You may test whether or not two floating point numbers are equal using FEQP, 
which takes the form 


Function: FEQP 

# Arguments: 2 

Arguments: 1) a number, X1 
2) a number, X2 

Value: T, if X1 equals X2 as a floating point 
number. 


Consider the following examples: 


+ (FEQP 0.0345 0.034) 
NIL 


< (FEQP) 
"non-numeric arg" 
NIL 


Note: this function is defined in INTERLISP-D only, although it is noted in 
the IRM [irm83] as being available in all versions of INTERLISP. 


374 Arithmetic Functions 


13.4.6 Floating Point Boolean Functions 
INTERLISP provides the corresponding boolean functions for comparing two 
floating point numbers: FGREATERP and FLESSP, which take the form 
Function: FGREATERP 
FLESSP 
# Arguments: 2 


. Arguments: 1) a number, X1 
2) a number, X2 


Value: T, if X1 is greater than, respectively 
less than, X2. 

Consider the following examples: 

<(FGREATERP 278.7 0.0345) 

sf 


«-(FLESSP 1.0004 1.00038) 
NIL 


13.4.7 Floating Point Minimum and Maximum 
You may determine the minimum or maximum of a sequence of floating point 
numbers using FMIN or FMAX, which take the form 
Function: FMIN 
FMAX 
# Arguments: 1-N 


Arguments: 1) a number, X1 
2) a number, X2 
3-N) numbers, X3 ... XN 


Value: The minimum or maximum, respectively, of 
the numbers Xi as a floating point number. 


FMIN and FMAX are nospread functions. Consider the following exam- 
ples: 


<—(FMAX 45.12 0.03 67834.23 -3.1415) 
67834 23 


Note that FMIN and FMAX return the smallest and largest floating point 
numbers, respectively, if their arguments are NIL. 
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< (FMIN) 
-3.402823 E38 


+ (FMAX) 
3.402823 E38 


13.4.8 Converting a Number to Floating Point Format 


You may convert a number to floating point format using FLOAT, which takes 
the form 


Function: FLOAT 

# Arguments: 1 

Argument: 1) a number, X 

Value: X, as a floating point number. 


FLOAT returns X directly if it is a floating point number. Otherwise, 
FLOAT converts X to a floating point number, e.g., 


(FLOAT 0) 
0.0 


«(FLOAT (ITIMES 23 78)) 
1794.0 


<— (FLOAT) 
"non-numeric arg" 
NIL 


13.5 MIXED ARITHMETIC FUNCTIONS 


INTERLISP provides a set of generic functions whose result takes on the charac- 
teristics of its arguments. If any argument of these functions is a floating point 
number, all arguments are coerced to floating point format and the result is a 
floating point number (unless it is T explicitly). Otherwise, these functions act 
like integer functions. Rather than give a detailed exposition of these functions, 
the following table depicts the correspondences between these generic functions 
and those that we have already discussed. 


Generic Function Integer Floating Point 
PLUS IPLUS FPLUS 
DIFFERENCE IDIFFERENCE FDIFFERENCE 


MINUS IMINUS FMINUS 
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TIMES ITIMES FTIMES 
QUOTIENT IQUOTIENT FQUOTIENT 
REMAINDER IREMAINDER FREMAINDER 
GREATERP IGREATERP FGREATERP 
LESSP ILESSP FLESSP 
GEQ IGEQ = --=== 

LEQ TLEQ wee 

MIN IMIN FMIN 

MAX IMAX FMAX 


13.5.1 Computing the Absolute Value 


You may compute the absolute value of a number using the function ABS, which 
takes the form 


Function: ABS 

# Arguments: 1 

Argument: 1) a number, X 

Value: The absolute value of X. 


ABS returns X if X is greater than zero; otherwise, it returns -X. Consider 
the following examples: 


«(ABS 23.0) 
23.0 

«(ABS 0.0) 
0.0 

<—(ABS -432.76) 
432.76 


The IRM [irm83] notes that ABS uses GREATERP and MINUS to perform 
its computations. 


A Definition for ABS 
We might define ABS as follows: 


(DEFINEQ 
(abs (x) 
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(COND 
((GREATERP x 0) x) 
(T 
(MINUS x))) 
)) 


13.6 SPECIAL ARITHMETIC FUNCTIONS 


INTERLISP provides a standard set of functions for performing commonly ac- 
cepted mathematical functions. These include exponentiation, trigonometric 
operations, logarithms, and random number generation. 


13.6.1 Trigonometric Functions 
INTERLISP provides the standard trigonometric functions. Each function takes 
a number, X, and returns its value as a floating point number. Their formats are 


Function: SIN 
Cos . 
TAN 


#Arguments: 2 


Arguments: 1) a number, X 
2) a flag, RADIANSFLAG 


Value: A floating point number. 


If RADIANSFLAG is T then X is in radians; otherwise, it is degrees. Con- 
sider the following examples: 


«(for I from 0.0 to 180.0 by 30.0 
do (PRIN1 I) (SPACES 5) (PRINT (SIN I))) 
0.0 0.0 


30.0 -4997781 
60.0 -8656472 
90.0 1.0 

120.0 8656472 
150.0 -04997779 
180.0 -1.87253 E-7 


where the values of SIN are small integers. 


«(for I from 0.0 to 180.0 by 30.0 

do (PRIN1 I) (SPACES 5) (PRINT (COS I))) 
0.0 1.0 
30.0 .8656472 
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60.0 -4997781 

90.0 0.0 

120.0 - .4997784 

150.0 - .865647 

180.0 -1.0 


where the values for COS are small integers. 


' (for I from 0.0 to 180.0 by 30.0 
do (PRIN1 I)(SPACES 5)(PRINT (TAN I))) 


0.0 0.0 

30.0 5773462 
60.0 1.732063 
90.0 3.402823 E38 
120.0 -1.732062 
150.0 -.5773461 


180.0 1.872535 E-7 


13.6.2 Inverse Trigonometric Functions 


INTERLISP also provides standard inverse trigonometric functions. Each func- 
tion takes a floating point number within the function’s input range. Arguments 
outside the proper range cause an error to be generated. Their formats are 


Function: ARCSIN 
ARCCOS 
ARCTAN 
# Arguments: 2 
Arguments: 1) a number, X 
2) a flag, RADIANSFLAG 
Value: A floating point number. 


The ranges for input and output for each of these functions are 


Function Input Output 

ARCSIN [-1.0, +1.0] [-90.0, +90.0] 
ARCCOS [-1.0, +1.0] [180.0, 0.0] 
ARCTAN [-1.0, +1.0] [134.9998, 45.0] 


RADIANSFLAG determines whether the result is returned in radians (T) or 
degrees (NIL). 
Consider the following examples: 
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(ARCCOS -1.3) 
ARCCOS: arg not in range 


-1.3 

<(ARCCOS 0.5) 

60.00001 

<(ARCCOS 0.0) 

90.0 

<(ARCTAN -0.5) 

153.4349 

<—(ARCTAN -1.0) 

135.0 

<—(ARCTAN 1.0) 

44 .99999 
Another View of ARCTAN 


An alternative form of ARCTAN, ARCTAN2, computes the quotient of two 
numbers, X and Y. ARCTAN2 has the format 

Function: ARCTAN2 

# Arguments: 3 


Arguments: 1) a number, X 
2) a number, Y 
3) a flag, RADIANSFLAG 


Value: A floating point number 
ARCTAN2 returns a value in the range —180 to +180 degrees, i.e., the 


result is in the proper quadrant as determined by the signs of X and Y. 
Consider the following examples: 


<(ARCTAN2 -1.0 0.5) 
-63.43495 


+ (ARCTAN2 0.0 1.0) 
-180.0 


«(ARCTAN2 1.0 0.0) 
90.0 


13.6.3 Exponentiation 


EXPT returns the value of its first argument, X, taken to the Nth power. Its 
format is 
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Function: EXPT 
# Arguments: 2 


Arguments: 1) a base, X 
2) a power, N 


Value: An integer or floating point number. 


_ If X and N are integers, EXPT returns an integer result; otherwise, it re- 
turns a floating point result. 


(EXPT 5 2) 

25 

«(EXPT -3 5) 
-243 

“(EXPT -0.7 10) 
0.2824752 


If X is negative (X < 0) and N is fractional (N ¢ 1.0), EXPT generates an 
error: 


«(EXPT -4 0.5) 
LOG OF NON-POSITIVE NUMBER 
-4 


If N is floating and either too large or too small, EXPT returns the largest 
possible floating point value. For example, 


(EXPT 150.0 25.0) 
3 .402823E38 


13.6.4 Square Root 


SQRT returns the square root of its argument, X, as a floating point number. Its 
format is 


Function: SQRT 

# Arguments: 1 

Arguments: 1) a number, X 

Value: A floating point number. 


Consider the following examples: 





13.6 Special Arithmetic Functions 381 


<(SQRT 106754.3) 
326.7328 


<(SQRT 81) 
9.0 


If X is negative (X < 0), SQRT generates an error: 


+ (SQRT -100.0) 
SQRT OF NEGATIVE NUMBER 
-100.0 


SQRT is faster than (EXPT X .5) as the following timing comparisons dem- 
onstrate (see Chapter 29 for a description of TIME): 


«(TIME (SQRT 100) ) 
0 Conses 

.173 seconds 

10.0 


«(TIME (EXPT 100 .5)) 
0 Conses 

.42 seconds 

10.00009 


13.6.5 Logarithms 


INTERLISP provides the natural logarithm function and its inverse. Their for- 
mats are 


Function: LOG 
ANTILOG 
# Arguments: 1 
Arguments: 1) a number, X 
Value: A floating point number. 


Consider the following examples: 


«(LOG 0.0) 
LOG OF NON-POSITIVE NUMBER 
0.0 


«(LOG 10.0) 
2.302583 


«-(LOG 100000.0) 
11.51292 
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If X is negative (X < 0), LOG and ANTILOG generate an error message: 


«(LOG -100.0) 
LOG OF NON-POSITIVE NUMBER 
-100.0 


<(ANTILOG -2.45). 
2.000018 


. #(ANTILOG 0.0) 
1.0 


“(ANTILOG -0.7) 
- 08629356 


13.6.6 Random Number Generation 
INTERLISP provides a psuedo-random number generator, RAND, and a func- 
tion for initializing it, RANDSET. The format for RAND is 

Function: RAND 

# Arguments: 2 


Arguments: 1) lower bound, LOWER 
2) upper bound, UPPER 


Value: An integer or floating point number. 


Consider the following examples: 


“(RAND 1 10) 

6 

<—(RAND 2 100) 

42 

«(RAND 1000 1050) 
1004 . 

«(RAND -150 -175) 
-164 

RANDSET takes the form 
Function: RANDSET 


# Arguments: 1 
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Argument: 1) an initialization value, X 


Value: An internal state. 


If X is NIL, RANDSET just returns the internal state. For example, 


 (RANDSET) 

(11996 58248 49267 19460 65470 24561 23941 48766 63093 
8937 26494 14191 25348 23161 58999 8788 20454 11637 62780 
33784 26916 44822 6238 60538 ...) 


If X is T, the random number generator is initialized using the current value 
of the system clocks, and RANDSET returns the new internal state. Otherwise, 
X is interpreted as a previous internal state, i.e., a value of RANDSET, which is 
used to reset the random number generator. For example, 


<(SETQ oldstate (RANDSET) ) 


<(RANDSET oldstate) 


where the internal state is represented as a long sequence of very large integers 
(too numerous to display here). 


13.7 MORE ARITHMETIC FUNCTIONS 


The two major LISP dialects diverged during their formative years. While IN- 
TERLISP emphasized programming productivity tools, MACLISP was devel- 
oped with numerical computation in mind. This split reflected the emphasis of 
the two communities’ research and development interests. Recently, we have 
seen a trend toward convergence of the two dialects (and other offshoots as well) 
in COMMONLISP. Neither dialect provides an extensive library of arithmetic 
functions beyond the normal ones found in programming languages. It is not 
hard, as this section demonstrates, to develop a fairly extensive set of arithmetic 
functions. 

In this section, we will describe some useful arithmetic functions. Usually, I 
will define these functions using arrays and CLISP operators. I leave it as an 
exercise for you to write the definitions that will work if the data structure to be 
operated upon is a list of numbers. 

Note: These functions are not included in the standard INTERLISP as of 


this writing. 
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13.7.1 Statistical Functions 


A good set of statistical functions should be in the repertoire of every program- 
mer. This section describes some definitions for the most commonly used statis- 
tical functions. 


Calculating the Mean 

Given an arry of numbers, the mean or average of that array is defined to be the 
sum of the elements of the array divided by the length of the array. MEAN takes 
the following format: 


Function: MEAN 

# Arguments: 1 

Argument: 1) an array, X 

Value: The mean of the array X. 


We might define MEAN as follows: 


(DEFINEQ 
(mean (x) 
(PROG (xsize xorigin xlimit xsum) 
(IF (ARRAYP x) 
THEN (RETURN NIL) ) 
xsize«(ARRAYSIZE x) 
xorigin« (ARRAYORIG x) 
(IF (ZEROP xorigin) 
THEN xlimit+-xsize-1 
ELSE xlimit«-xsize) 
xsum+-0 
(FOR I FROM xorigin TO xlimit 
DO xsum+-xsum+(ELT x i)) 
(RETURN 
(QUOTIENT xsum xsize))) 


)) 
Consider the following example: 
<(SETQ x (ARRAY 5 1)) 
{ ARRAYP }#1,2464 


«(FOR I FROM 1 TO 5 
DO (SETA X I (RAND))) 
NIL 
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«(MEAN X) 
38930 


where the elements of X are 54985, 50146, 17756, 63115, and 8650. 


Calculating the Median 

The median of an array of numbers is the value for which half the values are less 
than the median and half are greater. Given an array of numbers, we sort it in 
ascending order and inspect the midpoint to obtain the value of the median. 
MEDIAN takes the form 


Function: MEDIAN 

# Arguments: 1 

Argument: 1) an array, X 
Value: The median of X. 


We might define MEDIAN as follows: 


(DEFINEQ 
(median (x) 
(PROG (xsize y) 

(IF '"(ARRAYP x) 
THEN (RETURN NIL) ) 

y+ (ARRAYSORT x) 

xsize«(ARRAYSIZE x) 

(RETURN 
(ELT x (IQUOTIENT xsize 2)))) 


)) 


Calculating the Variance 

The variance of an array is defined as the average of the squares of the deviations 
from the mean. A deviation is merely the difference between an individual ele- 
ment of the array and the mean. VARIANCE takes the form 


Function: VARIANCE 

# Arguments: 1 

Argument: 1) an array, X 
Value: The variance of X. 


We might define VARIANCE as follows: 
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(DEFINEQ 
(variance (x) . 
(PROG (xmean xsize xorigin xlimit xmeansq 
xsumsq) : 
(IF ~(ARRAYP x) 
THEN (RETURN NIL) ) 
xmean* (MEAN x) 
xmeansq*- (TIMES xmean xmean) 
xsize+(ARRAYSIZE x) 
xorigin+ (ARRAYORIG x) 
(IF (ZEROP xorigin) 
THEN xlimit«-xsize-1 
ELSE xlimit+«xsize) 
(FOR i FROM xorigin to xlimit 
DO 
xsumsq ‘+ (DIFFERENCE 
(EXPT 
(FLOAT (ELT X T)) 
2.0)) 
xmeansq) ) 
(RETURN xsumsq) ) 


)) 


Calculating the Standard Deviation 
The standard deviation of an array is just the square root of its variance. Thus, 
we can define STANDARD.DEVIATIQN as 


(DEFINEQ 
(standard.deviation (x) 
(IF ~(ARRAYP x) 
THEN NIL 
ELSE (SQRT (VARIANCE x))) 


)) 


13.7.2 Complex Arithmetic 


INTERLISP does not support complex arithmetic (unlike FORTRAN), but we 
can simulate this feature using the Record Package (see Chapter 27). A complex 
number will be represented as a dotted pair, but it will be given its own datatype 
within INTERLISP. 


Defining Complex Numbers 
We can declare the definition of a complex number using the following expres- 


sion 
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«-(DATATYPE COMPLEX ((REAL FLOATP) (IMAG FLOATP))) 
COMPLEX 


and we may create a complex number using the following expression 


«(SETQ C1 (CREATE COMPLEX) ) 
[COMPLEX ]#170000 


Note that a new datatype has been created with the name COMPLEX and has 
been allocated its own storage pool for creating INTERLISP objects of that type. 
Let us create a second complex number, C2. 


<-(SETQ C2 (CREATE COMPLEX) ) 
[COMPLEX ]#170002 


But what we would really like to do is capture the creating function plus the 
setting of initial values in a single function. 


A Definition for Defining Complex Numbers 
We might define the function COMPLEX as follows: 


(DEFINEQ 
(complex (r i) 
(PROG (temp) 
(SETQ temp (create COMPLEX) ) 
(RECORDACCESS 'REAL temp NIL 'REPLACE r) 
(RECORDACCESS 'IMAG temp NIL 'REPLACE i) 
(RETURN temp) ) 


)) 


«(SETQ c3 (COMPLEX 7.5 9.0)) 
[COMPLEX ]#170770 


Accessing the Real and Imaginary Parts 
We may define two functions, REAL and IMAG, that access the real and imagi- 
nary parts of a complex number as follows: 


(DEFINEQ 
(real (cx) 
(RECORDACCESS 'REAL cx NIL 'FETCH) 
)) 


(DEFINEQ 
(imag (cx) 
(RECORDACCESS 'IMAG cx NIL ' FETCH) 
)) 
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«(REAL 3) 
765 


(IMAG c3) 
9.0 


Complex Addition and Subtraction 

Complex addition and subtraction are straightforward. We merely add or sub- 
tract the corresponding real and imaginary parts of the two complex numbers to 
produce a new complex number. We can define CPLUS and CDIFFERENCE as 
follows: 


(DEFINEQ 
(eplus (ex1 ex2) 
(PROG (cx3) 
(SETQ cx3 
(COMPLEX 

(PLUS (REAL cx1) (REAL ex2) ) 
(PLUS (IMAG cx1) (IMAG ecx2)))) 

(RETURN cx3)) 

)) 


(DEFINEQ 
(edifference (cx1 cx2) 
(PROG (cx3) 
(SETQ ex3 
(COMPLEX 
(DIFFERENCE (REAL cx1) (REAL cx2)) 
(DIFFERENCE (IMAG cx1) (IMAG ex2)))) 
(RETURN cx3)) 
)) 


«(SETQ c1 (COMPLEX 2.0 2.0)) 
[COMPLEX]#170002 


«(SETQ c2 (COMPLEX 3.0 3.0)) 
[COMPLEX] #170000 


«(SETQ c4 (CPLUS ¢c1 c2)) 
[COMPLEX ]#170752 


«(REAL c4) 
5.0 


<(IMAG ¢4) 
5.0 


<(SETQ ¢5 (CDIFFERENCE ¢1 c2)) 
[ COMPLEX] #170750 
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«(REAL ¢5) 
6 


«(IMAG c5) 
-1.0 


Note that I did not check to see if CX1 and CX2 were actually complex num- 
bers before performing the addition upon them. You can easily add the COND 
clause which checks this and prints the appropriate error message if they are not 
complex numbers. The conditional part of the COND clause appears as 


(TYPE? COMPLEX CX1) 


which returns T if CX1 is a complex number. 
Nor did I check if either of the arguments is NIL. If either (or both) argu- 
ment is NIL, we would like to assume a complex number equivalent to (0.0, 0.0). 


Defining Zero as a Complex Number 
You may define a function CZERO which creates the complex number having 
both parts equal to 0.0 as follows: 


(DEFINEQ 
(ezero nil 
(COMPLEX 0.0 0.0) 
)) 


Then, you may modify both CPLUS and CDIFFERENCE to check if either 
argument is NIL. If so, you merely set the argument (internal to the function) to 
(CZERO). Here is an example: 


(COND 
((NULL ecx1) 
(SETQ cx1 (CZERO)))) 


inside of CPLUS before you perform the addition. 


Multiplying Two Complex Numbers 

Multiplying complex numbers requires additional arithmetic because both real 
and imaginary parts must be reflected in the final product. Let CX1 and CX2 be 
complex numbers which have the representation 


ex1 = (a + bi) ex2 = (c + di) 


Then, the product of CX1 and CX2 is 
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(ex1 * cx2) 

(at+bi) * (c+di) 

ac + adi + bei + bdi**2 
(ac—bd) + (ad +be)i 


ex3 


We can define CMULT to multiply two complex numbers as follows 


(DEFINEQ 
(emult (ex1 cx2) 
(PROG (cx3) 
(SETQ ex3 
(COMPLEX 
(DIFFERENCE 
(ITIMES (REAL ecx1) 
(REAL cx2)) 
(ITIMES (IMAG cx1) 
(IMAG cx2))) 
(PLUS 
(ITIMES (REAL cx1) 
(IMAG cx2) ) 
(ITIMES (IMAG cx1) 
(REAL cx2))))) 
(RETURN cx3)) 


)) 


«(SETQ cx1 (COMPLEX 5.0 5.0)) 
[COMPLEX ]#460000 


(SETQ cx2 (COMPLEX 3.0 3.0)) 
[COMPLEX ]#460002 


<—(SETQ ex4 (CMULT cx1 cx2)) 
[COMPLEX ]#460012 


(REAL cx4) 
0.0 


<—(IMAG cx4) 
30.0 


You may define a similar function for performing the division of two com- 
plex numbers. I leave that as an exercise for the reader. 


Printing Complex Numbers 
The standard printing functions, when faced with a datatype that they do not 
know. how to print, will merely print its address representation. For example, 
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«(PRINT cx1) 
[COMPLEX ]#461000 


However, this does not inform us of the contents of CX1. We can define a 
method for printing complex numbers using DEFPRINT (see Chapter 15). The 
declaration takes the form 


*-(DEFPRINT 'COMPLEX (FUNCTION PRINT.COMPLEX) ) 
NIL 


<(DEFINEQ 
(print.complex (cx1) 
(LIST NIL (CONS (REAL cx1) (IMAG cx1))) 


)) 
(PRINT. COMPLEX) 


«(PRINT cx1) 
((5.0 . 5.0)) 


13.7.3 Additional Arithmetic Functions 


There are many other arithmetic functions which you may easily define that are 
not included in the standard INTERLISP loadup. This section describes a few of 
these functions. 


Truncation and Rounding 

You may want to truncate a number to its integer portion. One approach is to 
use FIX to yield the integer part of the number. An alternative method uses 
IQUOTIENT as shown below. Let us define TRUNCATE as follows: 


<— (DEFINEQ 
(truncate (x) 
(IQUOTIENT x 1) 


)) 
(TRUNCATE) 
«(TRUNCATE 5.4) 
2 


You may also want to round a number to the integer nearest a multiple of 
that number. We might define the function ROUNDTO as follows: 


<— (DEFINEQ 
(roundto (x y) 
(TIMES 
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(ROUNDED (QUOTIENT x y)) 


y) 
)) 
(ROUNDTO) 


where ROUNDED, which returns an integer nearest the argument, is defined as 
follows 


— (DEFINEQ 
(rounded (x) 
(TRUNCATE 
(PLUS x 
(QUOTIENT (SIGN x) 2))) 


)) 
(ROUNDED) 


and SIGN, which returns the sign of the argument, is defined as 


+ (DEFINEQ 
(sign (x) 
(COND 
((GREATERP x 0.0) 1) 
((LESSP x 0.0) -1) 
(T 1)) 
)) 
(SIGN) 


We can test these functions as follows: 


«(SIGN -5.4) 
at 


«(ROUNDED -5.4) 
a, 

«(ROUNDED 10.23) 
10 


«-(ROUNDTO 10.23 6) 
x 


Computing the Reciprocal 

The reciprocal of a number is one divided by that number. Obviously, we must 
check that we are not dividing by zero, and return an error if it is attempted. The 
main reason for defining RECIPROCAL is that gives a cleaner appearance to 
your functions than repreatedly writing (QUOTIENT 1.0 x). The name RECIP- 
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ROCAL is easier to understand than the expression above, although they do the 


same thing. 
We might define RECIPROCAL as follows: 


<— (DEFINEQ 
(reciprocal (x) 
(COND 
((EQP x 0.0) 
(ERROR "Zero has no reciprocal") ) 
T 
(QUOTIENT 1.0 (FLOAT x)))) 


)) 
(RECIPROCAL) 


(RECIPROCAL 2) 
oy) 


(RECIPROCAL 45.346) 
-02205266 


«(RECIPROCAL 0.0) 
Zero has no reciprocal 
NIL 


Obtaining the Floor of a Number 
The floor of a number is the nearest integer which is less than the number. We 


might define FLOOR as follows 


< (DEFINEQ 
(floor (x) 
(PROG (truncation) 
(SETQ truncation (TRUNCATE x) ) 
(COND 
((GEQ x 0.0) 
(RETURN truncation) ) 
((EQP x truncation) 
(RETURN truncation) ) 
(T 
(RETURN (SUB1 truncation) )))) 


)) 
(FLOOR) 


«(FLOOR 7.345) 
7 

«(FLOOR -34.98) 
-35 
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«(FLOOR -12) 
-12 


Note that the reason for the last test in the COND expression above is dem- 
onstrated by the two examples using negative numbers. The floor of —34.98 is 
not —34, because that number is greater than the original argument. On the 
other hand, the floor of —12 is —12. 

Equivalent arguments may be made for constructing a “ceiling” function 
which has a similar appearance. I leave this as an exercise for the reader. 

This demonstrates that new arithmetic functions may be added to your IN- 
TERLISP repertoire quite easily. Ideally, you want to collect the functions in a 
package, using the File Package commands, so that they may be loaded dynami- 
cally as needed. 
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Input Functions 


INTERLISP provides a rich variety of input functions for bringing data into a 
program. Input is mediated by read tables that describe how specific characters 
are to be interpreted. Most of the input functions take both an optional read 
table and an optional file. 

Input is terminated in an INTERLISP symbolic file by the character se- 
quence (CR)<LF) (e.g., a carriage-return, line-feed). INTERLISP-10 auto- 
matically ignores an (LF) appearing after a <CR) in a file. When you type a 
carriage return at your terminal, INTERLISP-10 automatically inserts a line 
feed after the (CR). 

Note that the internal representation of ‘‘end of line” differs between IN- 
TERLISP-10 and INTERLISP-D. INTERLISP-D uses the carriage return char- 
acter (15Q) while INTERLISP-10 uses the EOL character (37Q). By using 
(CHARCODE EOL) in your programs to look for end-of-line characters, you 
can make your programs implementation independent, since the EOL entry in 
the read tables will be set to the appropriate character code. 


14.1 READ: THE GENERAL CASE 


The most general case that we encounter in INTERLISP is reading S-expres- 
sions into a program. READ is the function that performs this operation for us. 
Its format appears as follows: 

Function: READ 

# Arguments: 1-3 


Arguments: 1) a file name, FILE 
2) an optional read table, RDTBL 
3) an optional flag, FLAG 


Value: An S-expression read from the file. 
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READ returns a value when one of two conditions is encountered: 


1. A carriage return is encountered in the file or has been typed by the user 
at the terminal. 


2. A right parenthesis is detected that matches a beginning left parenthesis 
and completes an S-expression. 


READ will properly read atoms, numbers, and strings as S-expressions 
when they are typed at the terminal without enclosing parentheses. Strings are 
delimited by double quotes as expected. Numbers are interpreted according to 
the current radix (normally, base 10). Numbers may be entered in a different 
radix by adding an identifying suffix to the number. 

READ echoes the characters that are typed at the terminal back to the ter- 
minal. Thus, when you type a carriage return, INTERLISP echoes both a car- 
riage return and a line feed so that new output will appear on the next physical 
line. If FLAG is T, then the carriage return normally typed after a matching 
right parenthesis will be suppressed. 

READ inputs an S-expression from the specified file. If the file name is NIL 
or empty, READ assumes that you meant the terminal and reads from T. Note 
that INTERLISP does not prompt you to enter any data, but merely waits until 
you type the proper input to proceed. 


<—(SETQ x (READ)) 
' 


cursor waits here for you to enter data 


«(SETQ x (READ) ) 
1.234¢CR) 
1.234 


<(NUMBERP x) 
1.234 


In this case, the atom typed in is interpretable as a number, so INTERLISP 
creates a number. The type of number depends on the nature of the atom that 
you type. Integers consist of a sequence of numeric characters without a decimal 
point. INTERLISP also ‘“‘understands”’ scientific notation: 


<(SETQ x (READ)) 
1E3<cr) 
1000.0 


The second number printed in the above cases is the result of evaluating the 
expression, while the first is just INTERLISP echoing what you typed in. 

You may specify the radix of the number that you are typing in by append- 
ing a radix identifier. INTERLISP assumes all numbers are entered in decimal. 
Appending a Q to the number indicates an octal number. 





14.1 READ: The General Case 397 


«-(SETQ x (READ) ) 
21Q 
vay Note: radix change! 


Because INTERLISP/370 maintains numbers in an internal hexadecimal 
format (due to the System/370 architecture), prefixing an @ to a number causes 
it to be interpreted as a hexadecimal number: 


«-(SETQ x (READ) ) 
@11 
16 


Strings are identified to READ by delimiting them by double quotes: 


«-(SETQ x (READ) ) 
"An ill wind blows no good" 
"An ill wind blows no good" 


Input from the terminal is line-buffered in order to permit control charac- 
ters (principally, backspacing and word delete) to be effective. No characters are 
passed from the input routines to the program until a (CR) has been typed. But, 
merely typing a (CR) indicates no input, and INTERLISP waits for further in- 
put. 


«(SETQ x (READ NIL NIL T)) 
tT 


typing <CR) does nothing; you must enter ) or ] to complete an S-expression, 
but 


«-(SETQ x (READ NIL NIL T)) 
HELP< CR) 
HELP 


<(SETQ x (READ NIL NIL T)) 


) 
NIL 


because ) completes an S-expression, which is in fact the empty list represented 
by NIL. 


14.1.1 Effect of Control Characters 


INTERLISP recognizes the effect of several characters (that is, pressing the 
CTRL key and a letter key simultaneously) when accepting input from the termi- 
nal. These control characters affect most input functions, although we discuss 
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them after READ. Note,that these control characters are often implementation- 
dependent. The following control characters are handled by INTERLISP-D and 
INTERLISP- 10: 


CTRL-A 
Erases the last character typed in by you. It echoes \ and the erased character. 


<(SETQ x (REEDTATAAD) ) 


is entered as (SETQ x (READ)) because ED was erased by the pair of CTRL-As 
that were typed. Note that what you really see on your terminal is 


«(SETQ x (REED\D\EAD) ) 


CTRL-B 
Forces a break in the current computation, whence the stack is backed up to the 
last function call and the BREAK package (see Chapter 20) is entered. 


—(SETQ x (READ) ) 

TB 

interrupted below \TTYBACKGROUND 
(\TTYBACKGROUND broken) 


While in INTERLISP-10, you would see 


+-(SETQ x (READ) ) 
TB 


BREAK 
NIL 


(READ broken) 


There are significant differences in the way the various implementations 
handle this interrupt. You should consult the IRM for the current description. 


CTRL-C 
Forces termination of the current computation and return of control to the oper- 


ating system. 


«(SETQ x (READ) ) 
Tc 
@ (which is the TENEX prompt) 
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CTRL-D 
Forces a termination of the current computation, followed by a reset, and re- 


winds the stack to the top level. Internally, it forces a call to RESET (see Chapter 
18). 


CTRL-E 
Forces an error in the current computation which is backed up to the last error- 


set; NIL is returned as its value. Internally, it forces a call to ERROR! (see 
Chapter 18). 


CTRL-H 

For INTERLISP-D, a menu of running processes is displayed from which 
you may select one to be interrupted. This will be discussed in more detail in 
Volume 2. 

For INTERLISP-10, at the next point that a function will be entered, IN- 
TERRUPT will be invoked instead. It prints the message ‘INTERRUPTED 
BEFORE (fn)’’, constructs an appropriate break expression, and calls 
BREAK1 (see Section 20.3.3). Break handling is described in Chapter 20. Note 
that CTRL-H breaks only when a function is to be entered, as opposed to 
CTRL-B which breaks immediately. It is “‘safer’’ to use CTRL-H since the envi- 
ronment is in a relatively clean state from which the computation may be re- 
sumed. 


CNTRL-O 
Clears the current contents of the terminal output buffer. 


<—(SETQ x "Now is the time for all good men to come to 
the aid of their country") 


«(PRINT x) 

"Now is the time for all goTOod men to come to the aid of 
their country" 

"Now is the time for all go 


The string is placed in the output buffer twice: once, as a result of the 
PRINT function, and once as a result of the function evaluation. When I inter- 
rupted it with a CTRL-O, the first instance had already been passed to PRINT, 
but the second remained in the output buffer. It is this second instance that was 
abruptly terminated because the output buffer was cleared. 

CTRL-O is not enabled in INTERLISP-D. 


CTRL-P 

Change the printlevel for the display of S-expressions by clearing and saving the 
input buffer, clearing the output buffer, and waiting for the user to enter a num- 
ber indicating the new printlevel. The input buffer is restored and the program 
continues. The printlevel is described in Section 15.3. 
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CTRL-Q 

Erases the input line buffer contents. It echoes # # and resets the buffer to the 
last carriage return. Note that you may type ahead several lines but only the last 
physical record is erased: 


«(SETQ x (READ NILTQ## 


whence you may start retyping the line. You may not use this character repeat- 
edly. 


CTRL-R 
Causes INTERLISP to retype the contents of the input buffer. It is used after 
several editing control characters to see where you are. 


<—(SELTATQ x 9T(REETAD NILTR 
(SETQ x (READ NIL 

tT 

cursor waits here for you to resume 
typing of characters to complete the expression. 


CTRL-S 

Allows you to change the minimum amount of storage to be maintained by the 
garbage collector. When CTRL-S is typed, the input buffer is cleared and saved, 
and INTERLISP waits for you to enter a number which is the amount of storage 
to be maintained. It must be terminated by a period; otherwise, it will be ig- 
nored. After the number is entered, the input buffer is restored and computation 
resumes. Storage management is discussed in Chapter 29. 

CTRL-S is not enabled in INTERLISP-D. 


CTRL-T 
Prints the total execution time for the program as well as its status. — 


TT : 
running in \TTYBACKGROUND in TTIWAITFORINPUT in TTBIN 
90% UTIL, 2% SWAP, 6% GC 


And, in INTERLISP-10 


TT 
IO WAIT IN READ IN LISPXREAD IN EVALQT, LOAD 1.5 


CTRL-U 
Forces the editor to be invoked for the current expression after it is read (IN- 


TERLISP-D). 
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«(SETQ x (READ NILTU NIL T)) 
(edit) 
x 


In INTERLISP-10, this control character erases the input buffer under 
TOPS-20. 


CTRL-V 

Allows you to enter an atom from the terminal which has a control character 
embedded within it. To do so, you type CNTRL-V followed by the character that 
you wish interpreted as a control character. Typing CNTRL-V C transmits the 
code equivalent to a CNTRL-C. 


CTRL-X 
Aborts printout, moves to previous expression and prints it; used in the editor 
(see Chapter 19). 


CNTRL-Y 
Returns result of evaluating next expression read as though it had been typed; a 
READ macro. 


CNTRL-Z 
Aborts printout, moves to last expression of current expression and prints it; 
used in editor (see Chapter 19). 


14.2 READING: SPECIAL CASES 


INTERLISP provides several functions for performing specific input functions. 
I refer to them as special cases only because they process information in different 
formats. They should not be construed as being unusual reading mechanisms. 


14.2.1 RATOM: Reading an Atom 


RATOM allows you to read a single atom from the specified file. Its format is 


Function: RATOM 
# Arguments: 2 
Arguments: 1) a file name, FILE 
2) a read table, RDTBL 
Value: The next atom encountered in the input 
stream. 


If FILE is NIL, RATOM attempts to read from the current input file. It will 
return an atom, determined by its PRIN1-PNAME representation, or a number 
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if one is read. However, RATOM performs no special processing for strings, so if 
"is encountered in the input stream, it will be returned as the next atom. Con- 
sider these examples: 


<—(SETQ x (RATOM) ) 
Come to the high country! 
Come 


“No do, collect, or join in 
- (to (the high country) ) 

Ushet 

to 


because DWIM is enabled (see Chapter 22). Let us disable it and see what hap- 
pens: 


<(DWIM NIL) 
NIL 


«(SETQ x (RATOM) ) 
Come to the high country! 
COME 


UNDEFINED CAR OF FORM 
TO 


because it returns to the READ-EVAL-PRINT loop. Thus, RATOM should be 
used primarily within a program where you have control over the input stream. 
Note that care must be exercised when reading using RATOM. 


<(SETQ x (RATOM)) 
"Baltimore is best'' 
g" 


because "' is a separator character. 

Note that a break or separator character that terminates input to RATOM is 
not read, but remains in the buffer to become the first character seen by the next 
input function that is called. 


14.2.2 Reading up to an Atom 


A variant of RATOM is RATOMS which reads atoms from the input file until a 
specific atom, the first argument, is read. This function allows you to scan the 
input stream for specific phrases that are prefaced by demarcating atoms. Its 
format is 
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Function: RATOMS 
# Arguments: 3 


Arguments: 1) an atom, ATM 
2) a file name, FILE 
3) A read table, RDTBL 


Value: A list of atoms from the current file up 
to, but not including, the atom ATM. 


Consider the following example: 


<(SETQ x (RATOMS '%])) 
Washington is a capital city] 
(Washington is a capital city) 


A Definition for RATOMS 
We might define RATOMS as follows: 


(DEFINEQ 
(ratoms (atm file rdtbl) 
(PROG (lst char) 
loop 
(SETQ char (RATOM file rdtbl)) 
(COND 
((EQ char atm) 
(RETURN (CAR lst))) 
((SETQ lst (TCONC lst char)) 
‘4 (GO loop) ))) 


Generally, you may use RATOMS to read text files up to, but not including, 
punctuation marks. Thus, you can read in phrases and sentences without read- 
ing the punctuation marks. 


14.2.3 Testing Atom Demarcators 


The action of RATOM is terminated by a break or separator character. Some- 
times you may want to know what type of character forced the termination of 
RATOM. RATEST allows us to determine the nature of this character. RA- 
TEST takes the form 


Function: RATEST 
# Arguments: 1 
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Arguments: 1) a flag, FLAG 


Value: T, if a separator was encountered 
immediately prior to the last atom read. 


RATEST takes one argument, FLAG, which determines the type of test to 
be performed. Its values are 


Value of FLAG , ype of Test 
| T Separator character 
NIL Break character 
1 Escape character 


RATEST returns T if the character preceding the last atom read was a sepa- 
rator or break character, NIL otherwise. For FLAG=1, RATEST returns T if 
the last atom contained an escape character. Consider the following examples: 


«(SETQ FLAG T) 
T 


«(PROG (TEMP) . 
(SETQ TEMP (RATOM)) 
(SETQ TEMP (RATOM) ) 
(RETURN (RATEST FLAG) )) 

COME TO 

T 


because the space between COME and TO is a separator character. 


«-(SETQ FLAG NIL) 
NIL 


+ (PROG (TEMP) | : 
(SETQ TEMP (RATOM) ) 
(SETQ TEMP (RATOM) ) 
(RETURN (RATEST FLAG) )) 

COME (TO 

T 

UNBOUND ATOM 

TO 


because the ( is a break character. 
See Section 14.4 for a discussion of the read tables and the effects of these 


different character types. 
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14.2.4 RSTRING: Reading a String 


RATOM treats " as a separator character that terminates the act of reading. 
Thus, RATOM cannot accept a string as input and return it as a string. If your 
program expects to receive a string, you should use the function RSTRING 
which makes a string of the next atom read. RSTRING takes the following form: 


Function: RSTRING 
# Arguments: 2 


Arguments: 1) a file name, FILE 
2) a read table, RDTBL 


Value: A string from FILE which is terminated by 
the next break or separator character. 


The action of RSTRING is terminated by the next break or separator char- 
acter that is encountered in the input stream. If the next input character hap- 
pens to be a break or separator character, RSTRING will return ''" which is the 
null string. Your program should explicitly test for the presence of the null string 
(otherwise program errors may result). 


<-(SETQ x (RSTRING) ) 
"Atlanta" 
"Atlanta" 


«(SETQ x (RSTRING) ) 
«CR) 


<—(SETQ x (RSTRING) ) 
HELP< CR) 
"HELP" 


The break or separator character terminating a string is not read, but re- 
mains in the buffer to be read by the next input function. CTRL-A, CTRL-Q, 
and CTRL-V all have the same effect as they do on READ. 


14.2.5 READC: Reading a Character 


Both RATOM and RSTRING return a complete syntactic unit as their value. 
These syntactic units are terminated by break or separator characters, and their 
effect is modified by the presence of escape characters (as defined by the read 
tables). Sometimes you may want to process the input on a character by charac- 
ter basis, perhaps taking special action as individual characters are recognized. 
One special action might be to read enough characters to recognize a unique 
command and then complete the rest of the command for the user. 
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READC reads a single character from a file. It takes the form 


Function: READC 
# Arguments: 2 


Arguments: 1) a file name, FILE 
2) a read table, RDTBL 


_ Value: The next character in the input stream. 


READC is unaffected by read tables. That is, it always returns the next 
character that it encounters in the input stream. READC is subject to line-buf- 
fering (see Section 14.6). 


«-(SETQ x (READC)) 
A 
A 


<(SETQ x (READC)) 
(A) 
2 ( 


14.2.6 Reading the Last Character 


Some algorithms, particularly those that process textual material, need to “back 
up”’ to see the last character that was read. When READC is executed, the char- 
acter read is removed from the input buffer. However, INTERLISP allows us to 
retrieve its value via LASTC, which takes the form 


Function: LASTC 

# Arguments: 1 

Arguments: 1) a file name, FILE 

Value: The value of the last character read from 
FILE. 


LASTC returns the last character read from the file which is its argument. 
Like READC, LASTC is unaffected by break, separator, or escape characters. 
Consider the following example: 


«(PROG (X) 
(FOR I FROM 1 to 5 (SETQ x (READC)) (PRINT x)) 
(RETURN (LASTC) )) 
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WATER< CR) 


ADWBvHyr=z 


where the last R is returned as the result of LASTC. 


14.2.7 Looking Ahead in the Input Stream 


In a similar fashion, you may need to look ahead in the input stream to see what 
character occurs next. Command or text processors based on LR(k) algorithms 
often need to “‘peek’”’ at the next character to determine what action to take with 
the current character. INTERLISP provides PEEKC to look ahead in the input 
stream. PEEKC takes the following form 


Function: PEEKC 
# Arguments: 2 


Arguments: 1) a file name, FILE 
2) a read table, RDTBL 


Value: The next character in the file. 


PEEKC returns the next character in the line buffer, but does not actually 
remove it. 

When PEEKC is used with terminal input, it is subject to line buffering. If 
the value of RDTBL is NIL, PEEKC returns the character as soon as it is typed. 
Otherwise, it waits until the line has been terminated (see Section 14.6). Con- 
sider the following example: 


«(PROG NIL 
(FOR I FROM 1 TO 5 
(PRIN1 (READC)) 
(SPACES 3) 
(PRINT (PEEKC)))) 
WATER 
A 


27IByH r= 
BDH H 
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where the % above indicates a null character as the next character in the input 
buffer. 


14.2.8 READLINE: Reading a Terminal Line 


Many times the input to a program will be a sequence of atoms that are to be 
treated as an entire unit. To read this with RATOM or READ would require an 
iterative loop encoded in your program. INTERLISP provides us with a conve- 
nient function, READLINE, that gathers a sequence of atoms up to a line termi- 
nator and returns it as a list. READLINE takes the following form: 


Function: READLINE 
# Arguments: 3 
Arguments: 1) a read table, RDTBL 


2) a line specifier, LINE 
3) a LISPX flag, LISPXFLAG 


Value: The next line from the terminal, returning 
it as a list. 


READLINE terminates when any of the following conditions are met: 


1. A carriage return (typed by the user) and not preceded by any spaces is 
encountered. 


If the terminal screen appears as follows: 

Enter Command: show all paths from main<CR) 

READLINE returns the list 

(SHOW ALL PATHS FROM MAIN) 

where “Enter command:” was printed by the subsystem as a ery 


2. A list terminated by ], in which case the list is included in the result. 
If the terminal screen appears as follows: 


Enter Rule: (Implies murder (or death homicide]<CR) 
READLINE returns the list 


(IMPLIES MURDER (OR DEATH HOMICIDE) ) 
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3. An unmatched ) or ], neither of which is included in the resulting list. 
If the terminal screen appears as follows: 


< DF ADD.TO.DOCUMENT.LIST] 
READLINE returns the list 
(DF ADD.TO.DOCUMENT. LIST) 


The action of READLINE in case 1 is modified if one or more spaces pre- 
cedes the carriage return or a list is terminated by a ). These spaces indicate that 
the input stream is to be continued on succeeding lines. READLINE prints “*...”’ 
and continues reading on the next line. 

READLINE is a general reading function that is used by LISPXREAD (see 
Section 25.5.1). It may be defined as 


(DEFINEQ 
(readline (rdtbl line lispxflag) 
(APPLY* LISPXREADFN T) 
)) 


where LISPXREADEN is initially set to READ, but may be redefined by your 
program. 
Consider the following examples: 


«(SETQ x (READLINE)) 
J 
(NIL) 


This allows you to type a function name followed by a ) or | to LISPX (see 
Section 25.2). The Programmers Assistant distinguishes between (name)] as a 
function invocation and <name)<CR) as the evaluation of a variable. 


<EDITF REAL] 
edit 
¥ 


which allows us to edit the function REAL, because READLINE is used at the 
top-level READ-EVAL-PRINT loop. 


14.2.9 Reading from a File 


You may want to read all of the S-expressions in a file without evaluating them. 
READFILE takes the form 
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Function: READFILE 

# Arguments: 1 

Argument: 1) a file name, FILE 

Value: A list of all the S-expressions in a file. 


READFILE reads successive S-expressions from a file until it encounters an 
end-of-file condition, which causes an error, or it reads the single atom STOP. 
Let us assume that we have a file named COMPLEX that contains some of the 
definitions for complex arithmetic that we described in the last chapter. We 
might read that file as follows: 


*-(READFILE 'COMPLEX) 

((FILECREATED '"21-JUL-84 10:52:01" (KAISLER)COMPLEX. .8 
3497 changes to: (VARS COMPLEXFNS COMPLEXCOMS) (FNS FLOOR 
ROUNDTO SIGN ROUNDEDTO RECIPROCAL TRUNCATE PRINT.COMPLEX 
CMULT) (RECORDS COMPLEX) previous date: '17-JUL-84 
21252226 os . 


READFILE reads the contents of the file as a single large S-expression. In 
this format, the S-expression is not very readable (by humans), so we usually 
pass the result of READFILE to PRINTDEF to prettyprint (see Section 15.7) 
the output. 


<(PRINTDEF (READFILE 'COMPLEX) ) 
((FILECREATED "21-JUL-84 10:52:01" <KAISLER)COMPLEX. .8 
3497 changes to: 
(VARS COMPLEXFNS COMPLEXCOMS) 
(FNS FLOOR ROUNDTO SIGN ROUNDEDTO RECIPROCAL 
TRUNCATE PRINT.COMPLEX CMULT) 
(RECORDS COMPLEX) 
previous date: "17-JUL-84 21:52:16" ... 


where the ... indicates that there is more in the file that we have not shown here. 


14.2.10 Skipping S-expressions in a File 


You may process input from a file using a combination of several input func- 
tions. In some cases, after reading portions of the next S-expression from a file, 
you may decide not to read the rest of the expression. This often happens when 
you are parsing input expressions and detect an error early in the expression. 
Usually, the nature of the error will preclude successful processing of the re- 
mainder of the expression. 

SKREAD, which allows you to skip expressions within a file, takes the fol- 


lowing form: 
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Function: SKREAD 
# Arguments: 2 


Arguments: 1) a file name, FILE 
2) an input string, REREADSTRING 


Value: A separator character or NIL. 


SKREAD has the effect of moving the file pointer ahead in the file to the end 
of the current S-expression (see Section 16.8). None of the S-expression which is 
skipped is transferred to memory. 

If you have already read some of the expression using READCs or RA- 
TOMs, this input should be assigned as the value of REREADSTRING. 
SKREAD assumes that it has already seen this input and traverses the rest of the 
expression. REREADSTRING allows you to keep the parenthesis and double- 
quote counts correct. 

SKREAD returns one of three values: 


1. %) if the first thing it encounters is a closing parenthesis. 

2. %|] if the read terminates on an unbalanced J, e.g., a ] that closes any 
number of open left parentheses. 

3. NIL, otherwise. 


SKREAD always uses FILERDTBL, the File Package read table, as its read 
table. 

Let us use the file COMPLEX to demonstrate the application of SKREAD. 
The first few expressions appear as displayed in Section 14.2.9 above. Thus, by 
executing the following sequence, we can see how SKREAD works: 


<(OPENFILE 'COMPLEX 'INPUT 'OLD) 
{KAISLER) COMPLEX. .8 


because we must open the file before we can read from it. 
«-(RATOM 'COMPLEX) 
%( 
<-(RATOM 'COMPLEX) 
FILECREATED 
«-(SETQ REREADSTRING (RATOM 'COMPLEX) ) 
gf 
«(SKREAD 'COMPLEX REREADSTRING) 
NIL 


<(RATOM 'COMPLEX) 
«KAISLER) COMPLEX. .8 
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where we have skipped the remaining characters of the date-time group in the 
file header. 


«(READ 'COMPLEX) 


3497 

“(READ 'COMPLEX) 
changes 

“-(SKREAD 'COMPLEX) 
NIL 


«(READ 'COMPLEX) 
(VARS COMPLEXFNS COMPLEXCOMS) 


and so on. As you can see, SKREAD allows you to selectively read the expres- 
sions within a file. 


14.3 INPUT PREDICATES 


Many programs accept input from different sources such as several files, which 
may be written during the program’s execution, the terminal, or the Ethernet 
interface. The input functions discussed in the previous two sections all wait for 
input if none is available when the reading function is executed. If line buffering 
is activated for the terminal, a program executing a “‘read’’ against the terminal 
must wait until you terminate the line with a carriage return. If you must think 
about your answer, the program cannot proceed to do anything else. We would 
like to be able to test the input file to determine if input is available. If none is 
available, the program can do other useful work. A similar situation applies to 
reading from files that are dynamically created during program execution 
(avoiding deadlock) and the Ethernet interface. 

INTERLISP provides two predicates to test for the availability of input from 
a file: READP and WAITFORINPUT. 


14.3.1 READP: Testing Input 


READP tests the input buffer of the specified file to determine if any input is 
available. It returns T if input is available, but NIL otherwise. It takes the form 


Function: READP 
# Arguments: 2 
Arguments: 1) a file name, FILE 
2) a flag, FLG 
Value: T, if there is input waiting in the 


buffer. 
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FLG is used to determine if there is a single EOL (end-of-line) character 
remaining in the buffer. Normally, READP returns NIL while assuming that the 
EOL character is left over from the previous input. However, if you want to de- 
tect this condition, set FLG to T and READP will return T. 

You must exercise caution when using READP. It will return T if there is 
input in the line buffer for a line that has not been terminated by the user. Even 
though READP returns T, READ may have to wait until the user terminates the 
line. 


(PROG (char) 
(SETQ char (READC) ) 
(RETURN (READP) ) ) 
WATER< CR) 
T 


because the characters ATER remain in the input buffer. 


«(PROG (char) 
(SETQ char (READC)) 
(RETURN (READP) ) ) 
M<CR) 
‘3 


because it sees the (CR) as a character and treats it as remaining input. 


«(PROG (atm) 
(SETQ atm (READ) ) 
(RETURN (READP) ) ) 
WATER< CR) 
NIL 


because the (CR) is required to terminate the atom, is read by READ, and so, 
there is no input remaining in the buffer. 


«(PROG (atm) 
(SETQ atm (READ) ) 
(RETURN (READP) )) 
]<CR) 
ji 


because the ] terminates an expression, but the (CR) remains in the input 


buffer. 
If FILE is not open, READP generates an error FILE NOT OPEN (file- 


name). 
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14.3.2 Waiting for Input 


At other times a program may not be able to proceed until it receives input from 
the terminal or a file. WAITFORINPUT allows you to suspend program execu- 
tion until input is available. It takes the following form: 


Function: WAITFORINPUT 

# Arguments: 1 

Argument: 1) a file name, FILE 

Value: The name of the file for which input is 
available. 


It waits for input from either the specified file or the terminal. Its value is 
either T, indicating input is available at the terminal, or the file name, indicat- 
ing input is available in the file. 

WAITFORINPUT operates as a timed wait routine. That is, it waits for a 
specified amount of time, given by DISMISSMAX, and then returns NIL. This 
prevents the program from being deadlocked because no input is forthcoming 
from the terminal or the file. 

Internally, WAITFORINPUT uses the algorithm 


— 


. Suspend execution for a time interval, given by DISMISSINIT, the ini- 
tial interval. 


. Check for input from file or terminal. 

. If input is available, return T or the file name as appropriate. 

Add the interval to the total wait time. 

. If the total wait time exceeds DISMISSMAX, return NIL. 

. If no input is available, increase the wait interval by a specified factor 
(1/16 according to the IRM). The wait interval increases up to the maxi- 
mum interval, given by DISMISSMAX. 

. Suspend execution again. 


8. Goto 2. 


nu Fk wWhnd 


~I 


The value of the argument may also be an integer that specifies how long 
WAITFORINPUT should wait before returning to the calling function. In this 
case it waits until the specified number of milliseconds has elapsed and then 
returns NIL if no input has become available at the terminal. Note that this form 
overrides the action associated with the value of DISMISSMAX. 

WAITFORINPUT will be extremely useful in those environments where you 
have multiple cooperating processes running within your INTERLISP environ- 
ment. As processes are only supported under INTERLISP-D, a demonstration 
of WAITFORINPUT will be deferred until Volume 2. 
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14.4 CONCEPT OF THE READ TABLE 


INTERLISP allows you to decide how characters in the input stream are to be 
processed. The mechanism for controlling parsing (e.g., interpretation) of input 
character sequences is driven by a data structure known as the read table. Read 
tables are media-independent. That is, the interpretation of the character is the 
same regardless of the device from which the read operation is being performed. 

Read tables provide the system with information about the syntax class of 
each character. Characters may assume different roles in different functions or 
programs depending on their read table descriptions. Roles include specification 
of breaks, separators, escapes, and list or string delimiters. You may define mul- 
tiple read tables within a program. You may switch among them by providing 
the address of the read table as an argument to an input function or you may 
declare a read table to be effective by a function call. 

INTERLISP itself utilizes three default read tables to simplify the interpre- 
tation of characters in different subsystems: 


T for terminal input/output 
FILERDTBL for file input/output 
EDITRDTBL for editor input from a terminal 


INTERLISP provides functions for changing or resetting the default read 
tables or copying them to create new specialized ones. You may also create new 
read tables by specifying their contents explicitly. 


14.4.1 Syntax Classes 


A syntax class is a group of characters that have the same effect with respect to a 
particular input or output operation. The read table associates a character with 
its syntax class. When an input or output operation detects a character, it uses 
the syntax class to determine what to do. There are nine syntax classes in all. 

Six of the syntax classes form a special group known as format characters. 
These classes are 


Syntax Class Initial Value 


LEFTBRACKET [ 
RIGHTBRACKET ] 
LEFTPAREN ( 
RIGHTPAREN ) 
STRINGDELIM " 
ESCAPE % 


LEFTPAREN and RIGHTPAREN are used to begin and end list struc- 
tures, respectively. 
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LEFTBRACKET and RIGHTBRACKET are used to begin and end list 
structures, respectively. RIGHTBRACKET can be used to close any number of 
LEFTPAREN lists or back to the last LEFTBRACKET. 

STRINGDELIM is used to begin and end a text string. Within a string, all 
characters except those assigned to the ESCAPE class are treated as ordinary 
characters (i.e., belonging to class OTHER). A STRINGDELIM character may 
be included in a text string by prefixing it with an ESCAPE character. 

ESCAPE inhibits any special interpretation of the character immediately 
following it in the character stream (i.e., the character is treated as belonging to 
class OTHER). 

If you assign another character to one of these syntax classes, it does not 
disable the character that is currently defined. We can make { be interpreted as 
a LEFTBRACKET character by 


+-(SETSYNTAX '%{ 'LEFTBRACKET) 
OTHER 


-(SETSYNTAX '%} 'RIGHTBRACKET) 
OTHER 


«(SETQ x (READ)) 
{ATLANTA IS A PEACH OF A CITY} 
(ATLANTA IS A PEACH OF A CITY) 


which tells INTERLISP that { is to be treated as a left bracket like [ and } asa 
right bracket like ]. 

Two syntax classes are used to distinguish atoms in an input stream, princi- 
pally by RATOM. These classes are BREAKCHAR and SEPRCHAR. In fact, 
there are several break characters recognized by INTERLISP and these are 
jointly referenced by the syntax class BREAK. BREAK is the union of the 
classes LEFTPAREN, RIGHTPAREN, LEFTBRACKET, RIGHTBRACKET, 
STRINGDELIM, AND BREAKCHAR. 

Both BREAK and BREAKCHAR may be used in SETSYNTAX (see Sec- 
tion 14.4.3). However, you must be careful in using them to define a break char- 
acter. Compare the results of the following when the input sequence below is to 
be read: 


input sequence: (EQ FRUITS '(APPLES ORANGES) ) 


normal mode: 


(READ) 
(EQ FRUITS '(APPLES ORANGES) ) 


alternative mode: 


<(SETSYNTAX '%( 'BREAK) 
LEFTPAREN 
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(READ) 
(EQ fruits '(apples oranges) ) 
(EQ fruits ' (apples oranges) ) 
Tt 
note the space between ' and the list. 


alternative mode: 


+ (SETSYNTAX '%( 'BREAKCHAR) 
LEFTPAREN 


< (READ) 

(EQ fruits '(apples oranges) ) 
%( 

=.,.2)0.b.a 


fruits 


A given character may be disabled by assigning it the syntax class OTHER. 
Disabling a character means that it no longer is interpreted as a specific class. 
All characters belonging to the class OTHER have just their literal values when 
read by INTERLISP. 


14.4.2 Getting the Syntax Class 
You may get the syntax class of a character by executing GETSYNTAX, which 
takes the form 

Function: GETSYNTAX 

# Arguments: 2 


Arguments: 1) a character, CHAR 
2) a read table, RDTBL 


Value: The syntax class of CHAR. 
GETSYNTAX returns the syntax class of the character with respect to the 


specified read table. If read table is T or NIL, the terminal read table is as- 
sumed. 


<(GETSYNTAX '%() 
LEFTPAREN 


<(GETSYNTAX 'A) 
OTHER 


«-(GETSYNTAX (CHARCODE &) ) 
OTHER 
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+ (GETSYNTAX 13) 
SEPRCHAR 


You may also specify a syntax class name as the value of the first argument. 
If so, GETSYNTAX returns a list of the character codes that comprise that 
class. 


+ (GETSYNTAX 'BREAK) 
. (34 40 41 91 93 123 125) 


*-(GETSYNTAX 'SEPRCHAR) 
(9 10 12 13 31 32) 


Special Syntax Functions 

Because these expressions are commonly used, INTERLISP provides functions 
for accessing the break and separator characters of a read table. They take the 
form 


Function: GETBRK 
GETSEPR 
# Arguments: . 1 
Arguments: 1) a read table address, RDTBL 
Value: A list of the break or separator 


characters, respectively, for the 
specified read table. 


Consider the following examples: 


< (GETBRK) 
(34 40 41 91 93) 


< (GETSEPR) 
(0:9: 10 1%, 42: 13:31. 32) 


«-(GETBRK EDITRDTBL) 
(23 34 40 41 91 93 124) 


14.4.3 Setting the Syntax Class 


You may set the syntax class using the function SETSYNTAX. SETSYNTAX 
sets the syntax class of a character for a specified read table. The read table may 
be T or NIL or ORIG which means to set the syntax in the terminal read table. 
You may also specify either of the other system read tables or one of your own. 
Its format is 
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Function: SETSYNTAX 
# Arguments: 3 


Arguments: 1) a character or character code, CHAR 
2) a syntax class, CLASS 
3) a read table, TABLE 


Value: The previous syntax class of the 
character. 


If CLASS has the value T or NIL or ORIG, SETSYNTAX assumes that you 
want to set the syntax class to that defined in the terminal read table: 


«(SETSYNTAX '%{ 'ORIG) 
OTHER 


means to set the syntax class of { as it originally was. CLASS may also be another 
read table whence the syntax class of the character in that read table is made the 
syntax class of the character in the specified read table. 


*-(SETSYNTAX '%{ FILERDTBL EDITRDTBL) 
OTHER 


Finally, CLASS may have the form 
(<type) <options) <function)) 
as described in the definition of read macros (see Section 14.4.5). 


Special Syntax Functions 

Because users often want to set the break or separator characters to meet specific 
needs, INTERLISP provides two explicit functions for this operation. They take 
the form 


Function: SETBRK 
SETSEPR 
# Arguments: 3 


Arguments: 1) a list of character codes, LST 
2) a flag, FLAG 
3) a read table address, RDTBL 


Value: NIL 


SETBRK and SETSEPR set LST as the values of the break and separator 
characters, respectively, in the specified read table. If LST is T, the separator 
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characters in RDTBL are set to be those in T, the system read table for termi- 
nals, regardless of the value of FLAG. 

If FLAG is NIL, RDTBL has only those elements in LST as separator char- 
acters; all old separator characters are discarded from RDTBL which are not in 
LST. If FLAG is 0, it removes from RDTBL as separator characters those char- 
acters that appear in LST (e.g., it acts like an UNSETSEPR function). If FLAG 
is 1, it makes each of the characters in LST be a separator character in RDTBL 
(e.g., it acts like an OR between LST and RDTBL with respect to separator 
characters). 

If RDTBL is T, then the separator characters are set to be those in the origi- 
nal system table. 


The Escape Character 

% has a special meaning in INTERLISP to identify non-printing characters. 
You may cause % to be interpreted like every other character on input using 
ESCAPE, which takes the form 


Function: ESCAPE 

# Arguments: 2 

Arguments: 1) a flag, FLAG 
2) a read table, RDTBL 

Value: The previous setting for the escape 
character. 


If FLG is NIL, then % is just another character to be read (e.g., it is set to 
class OTHER). Initially, the setting is T. It returns the previous class of %. 


14.4.4 Testing the Syntax Class 
You may test the syntax class of a character code within a specific read table 
using SYNTAXP, which takes the form 

Function: SYNTAXP 

# Arguments: 3 


Arguments: 1) a character code, CODE 
2) a syntax class, CLASS 
3) a read table, RDTBL 


Value: T or NIL. 


SYNTAXP returns T if the character code is a valid member of the syntax 
class in the specified read table; otherwise, NIL. The syntax class may be any of 
the standard syntax classes or one of the read macro options that are described 
in Section 14.4.5. Note that SYNTAXP accepts only character codes. 
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+ (SYNTAXP 40 'LEFTPAREN) 
ss 


<(SYNTAXP 2%( 'LEFTPAREN) 
Non-Numeric ARG 


( 


+-(SYNTAXP 100 'OTHER) 
T 


The atom BREAK may be used to refer to the class of all break characters; 
that is, it is the union of LEFTPAREN, RIGHTPAREN, LEFTBRACKET, 
RIGHTBRACKET, STRINGDELIM, and BREAKCHAR as explained above. 
In a similar fashion, the atom SEPR corresponds to all separator characters; it is 
equivalent to SEPRCHAR. 


14.4.5 Read Macros: Defining User Syntax Classes 


You may define your own interpretations of characters by associating them with 
read macros in a read table. A read macro is a definition that is substituted for a 
character when the character is read from an input stream. The definition for a 
read macro character is given by a function. The interpretation may be modified 
by one of several options. 


Types of Read Macros 
There are three types of read macros: 


MACRO When a character is read, its 
definition is inserted in the 
expression created by the input 
function instead of the read macro 
character. For example, the IRM 
[irm83] notes that we could define as 
a read macro as follows: 


(MACRO 
(LAMBDA (file rdtb1) 
(LIST 'NOT (READ file rdtb1)))) 


so that an expression of the form 
(AND a b)) 
would be returned as 


(NOT (AND a b)) 


SPLICE The definition of the macro is 
NCONCed into the resulting input 


422 Input Functions 


expression. The result of the macro 
should be a list or NIL. The IRM 


[irm83] notes that we could define $ 
as follows: 


(SPLICE 
(LAMBDA NIL 
(APPEND <atom)))) 


such that if the value of the (atom) is (A B C), then the expression (X $ Y) would 
be returned as (X A B C Y) when it is read from the input stream. 


INFIX The function that is the definition 
of the character is called with a 
list of what has been read. The list 
is passed to the function in TCONC 
format as the function's third 
argument. The function's value is 
treated as the new TCONC list. The 
IRM [irm83] notes that + could be 
defined as follows: 


(INFIX 
(LAMBDA (file rdtbl dummy) 
(RPLACA (CDR dummy) ) 
(LIST 'IPLUS 
(CADR dummy) 
(READ file rdtb1))) 
dummy ) ) 


If the function returns NIL, the read macro character is ignored, and read- 
ing of characters continues. Otherwise, if the function returns a TCONC list of 
one element, that element is the value of the READ. 

Read macro interpretation may be modified by specifying several options. 
The options list includes 


ALWAYS The character will always be treated 
as a break character (except when 
preceded by an escape character). 
This is the default interpretation of 
the macro. 


FIRST The character is not a break 
character. It will be interpreted as 
a read macro character only when it 
is the first character read after a 





ALONE 
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break character. For example, ' 
(single-quote) is interpreted as the 
abbreviation for (QUOTE ...) only 
when it is seen as the first 
character in an expression. Thus, 
atoms such as DON'T are properly 
read. 


The character is not a break 
character. It is interpreted as a 
read macro character only if it would 
have been read as a separate atom. 
That is, its immediate right and left 
neighbors are either break or 
separator characters. For example, * 
is defined as an ALONE read macro 
character in order to implement the 
comment pointer feature. 


Note that the three options described above are disjoint; that is, one and 
only one may be specified for any macro at any instant. 


ESCQUOTE 
ESC 


NOESCQUOTE 
NOESC 


The character will be preceded by an 
escape character when it is printed 
by PRIN2. This is the default 
interpretation. 


The character is printed without a 
preceding escape character. For 
example, ' is a NOESCQUOTE character. 
The IRM notes that you should be 
especially careful of declaring 
NOESCQUOTE read macro characters in 
FILERDTBL as they are likely not to 
be read back in properly after they 
have been written out. 


These two options are obviously mutually exclusive. They control whether or 
not the read macro character is protected by the ESCAPE character on input. 


IMMEDIATE 


The character is treated as an EOL as 
soon as it is read. This causes the 
rest of the line to be passed to the 
input function. A <CR)<LF) is 
printed. These characters take effect 
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immediately rather than waiting for 
the line to be terminated normally. 


NONIMMEDIATE The character is not interpreted 


until a carriage return, matching 
right parenthesis, or matching right 
bracket is read. This is the default 
interpretation. 


These two options are obviously mutually exclusive. They determine when a 
macro’s function is actually executed. 

The default options are ALWAYS, NONIMMEDIATE, and ESCQUOTE. 

Read macros are declared via SETSYNTAX. The form of the declaration is 


(<type) <options) <function)) 


14.4.6 Standard Read Macro Characters 
INTERLISP defines a number of standard read macro characters: [irm83]: 


CTRL-Y 


The single-quote character is defined in the T 
and EDITRDTBL read tables. It returns the next 
expression that is read as the argument to the 
function QUOTE. It is defined as a FIRST read 
macro so that it has no effect when encountered 
in the middle of a symbol. It will also be 
ignored if it is immediately followed by a 
separator character. 


This control character is defined in T and 
EDITRDTBL. Its effect is to return the result 
of evaluating the next expression that is read. 
Thus, if you type CTRL-Y followed by an atom or 
expression, the value of the atom or expression 
is returned in the result from the input 
function. For example, 


+-(SETQ keys (LIST TY(ARRAY 10))) 
({ ARRAYP }#542635) 


The back-quote character acts like quote, 
except that it causes the expression to be 
evaluated. The back-quote read-macro acts like 
a template. An example of its definition is 
given in Section 14.4.8. 


This read macro character implements the ?= 


(on-line help) of the Programmer's Assistant 
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(see chapter 25). It is defined in T and 


EDITRDTBL. 

* This read macro character implements the 
comment pointer feature. It is defined in 
FILERDTBL. 

CTRL-W This read macro control character is defined in 


T and EDITRDTBL. In INTERLISP-10, it deletes 

the entire previous expression that was typed 
in. In INTERLISP-D it deletes the previously 

typed "word." 


The vertical bar read macro character is 
equivalent to the back-quote read macro since 
some terminals do not have the back-quote symbol 
on their keyboard. It is also used to support 
the printing and reading of unusual data 
structures (see HPRINT). 


14.4.7 Read Macro Functions 
Read macro functions allow you to enable or disable the effect of read macros, 
and to test whether or not any read macros are in effect. 


Enabling or Disabling Read Macros 
READMACROS enables or disables the effect of any read macros that are de- 


fined. It takes the form 


Function: READMACROS 
# Arguments: 2 


Arguments: 1) a flag, FLAG 
2) a read table, RDTBL 


Value: The previous setting. 


READMACRO is used to enable or disable the effect of read macros in the 
specified read table. If FLAG is NIL, the effect of read macros is disabled. A 
value of T for FLAG will enable the effect of read macros. 


Testing for Read Macro Execution 
You may test if your program is executing under a read macro function using 


INREADMACROP, which takes the form 


Function: INREADMACROP 
# Arguments: 0 
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Arguments: NIL 


Value: The number of unmatched parentheses or 
brackets; otherwise, NIL. 


INREADMACROP returns NIL if you are not currently executing under a 
read macro function, Otherwise, it returns the number of unmatched left paren- 
theses or left brackets. 


Setting the Read Macro Flag 
SETREADMACROFIG sets the internal system flag that informs READ that it 
is under a read macro function. It takes the following form: 


Function: SETREADMACROFLG 

# Arguments: 1 

Argument: 1) a flag value, FLG 
Value:: The old value of the flag. 


When the flag is set, unmatched right parentheses or brackets will cause the 
error message “‘READ MACRO CONTEXT ERROR” to be displayed and a 
break to occur. This function disables that error message when debugging read 
macro functions. 

Note that the read macro functions are primarily for use in functions that 
are associated with read macros. 


14.4.8 BQUOTE: An Example of a SPLICE Macro 


BQUOTE is a back-quote facility provided as a Lisp User package. It takes 
forms having the structure ‘(form) and treats them as ’(form) except that any 
expression preceded by a “,” will be evaluated. This facility is similar to a read 
macro provided by MACLISP [char80]. BQUOTE handles several different 


forms: 


1. An expression preceded by a “‘,’ is merely evaluated and the value substi- 
tuted in the form for the expression. 

2. An expression preceded by “,@’ is evaluated and spliced in using AP- 
PEND. 

3. An expression preceded by “,.” is spliced in using NCONC. 


Consider the following example: 


'(A ,B ,@C ,.D E) 
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is equivalent to 


(CONS 'A 
(CONS B 
(APPEND C 
(NCONC D '(E))))) 


BQUOTE is implemented as a read macro. When ‘<form) is read, it is 
transformed to (BQUOTE <form)) and evaluated. Loading the BQUOTE pack- 
age places the read macro in T, FILERDTBL, and EDITRDTBL. 


A Definition for BQUOTE 
BQUOTE is declared as follows: 


(SETSYNTAX ' 
"(SPLICE 
(LAMBDA (file rdtb1l) 
(SELECTQ (PEEKC file) 
(' (READC file) 
(LIST (READBQUOTE file 
rdtb1) )) 
NIL) )) 
FILERDTBL) 


READBQUOTE is defined as follows: 


(DEFINEQ 
(readbquote (file rdtb1) 
(RESETLST 
(RESETSAVE 
NIL 
(LIST 'SETSYNTAX 
! 


5] 
(SETSYNTAX 
! 
3 
'(MACRO FIRST 
(LAMBDA (file rdtb1) 
(SETQ comma 
(SELECTQ (PEEKC 
file) 
(%. (READC file) 
! 


x* 
(, (READC file) 
ry 
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(1! (READC file) 
',1) 


(@ (READC file) 
',@) 


'5)))) 
rdtbl) 
rdtb1) ) 
(PROG (comma form) 
(SETQ form (READ file rdtb1) ) 
(RETURN 
(COND 
ee (LIST 'BQUOTE form) ) 
Tr 
. (KWOTE form)))))) 


14.5 READ TABLE FUNCTIONS 


A number of functions are provided to allow you to manipulate read tables. Note 
that you may have any number of read tables defined in your applications envi- 
ronment, but only one may be active for each of the three functional areas: T, 
EDITRDTBL, and FILERDTBL. However, you may replace the system default 
read tables with ones of your own choosing, and you may do so on a dynamic 
basis. 


14.5.1 Testing a Read Table 


READTABLEP allows you to test whether or not an object is the address of a 
read table. It takes the form 


Function: READTABLEP 

# Arguments: 1 

Argument: 1) a read table address, RDTBL 

Value: RDTBL, if RDTBL is the address of a read 
table. 


Note that READTABLEP returns T if the terminal read table or system 
read table (i.e., ORIG) happens to be the object specified. 


14.5.2 Obtaining a Read Table Address 


INTERLISP maintains several different read tables which are selected depend- 
ing on the input function that is to be performed. You may obtain the address of 
a specific read table using GETREADTABLE, which takes the following form: 
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Function: GETREADTABLE 
# Arguments: 1 

- Arguments: 1) a read table address, RDTBL 
Value: The address of a read table. 


If RDTBL is the address of a valid read table, this value is returned as the 
result of GETREADTABLE. Usually, RDTBL takes the values T or NIL which 
are interpreted as follows: 


1. If RDTBLis T, GETREADTABLE returns the address of INTERLISP’s 
read table for terminals. 


2. If RDTBL is NIL, GETREADTABLE returns the address of the primary 
read table. 


If RDTBL is not the address of a read table, INTERLISP generates an error 
message “ILLEGAL READTABLE”. 

INTERLISP maintains a separate read table for reading data from files. 
The address of this read table is stored in the variable FILERDTBL. 


14.5.3 Setting a Read Table 


You may set the primary system read table or the terminal read table using 
SETREADTABLE, which takes the form 


Function: SETREADTABLE 


# Arguments: 2 


Arguments: 1) a read table address, RDTBL 
2) a flag, FLG 


Value: The previous address of the read table. 


SETREADTABLE sets the primary read table to the read table whose ad- 
dress is given as the value of RDTBL. In addition, if FLG is T, SETREAD- 
TABLE also sets the terminal read table as well. 

You may reset the other read tables by assigning the new read table address 
to the appropriate variable: EDITRDTBL for the editor or FILERDTBL for the 
File Package. 


14.5.4 Copying a Read Table 


COPYREADTABLE returns the address of a copy of the specified read table. It 
takes the form 
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Function: COPYREADTABLE 

# Arguments: 1 

Argument: 1) a read table address, RDTBL 
Value: The address of a new read table. 


COPYREADTABLE is the only way by which you can create a new read 
table in INTERLISP. RDTBL is interpreted as follows: 


1. If RDTBL is the address of a valid read table, a copy of that read table is 
created and its address is returned to you. 


2. If RDTBL is NIL, a copy of the primary system read table is made and its 
address is returned to you. 


< (COPYREADTABLE) 
[READTABLEP ]#542224 


3. If RDTBL is T, a copy of the system terminal read table is made and its 
address is returned to you. 


<(COPYREADTABLE T) 
[READTABLEP ]#542427 


as 


If RDTBL is ORIG, a copy of the original system read table is made and 
returned to you. 


<-(COPYREADTABLE 'ORIG) 
[READTABLEP ]#542632 


5. Otherwise, an error is generated: ILLEGAL READTABLE. 


14.6 LINE BUFFERING 


Characters typed in at your terminal are normally placed in a line buffer. When 
an input function requests a character or sequence of characters, they are ex- 
tracted from the line buffer and transferred to the requesting function when a 
carriage return is typed. Until a carriage return is typed, you may delete charac- 
ters from the line buffer by typing CTRL-As or delete its entire contents by typ- 
ing CTRL-Q. 

An important consideration in line buffering is which function will process 
the input. This function determines whether or not parenthesis counting is ob- 
served. 
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<— (PROGN 
(RATOM) 
(READ) ) 
(rigel betelgeuse polaris) 


where you typed in 
aldebaran (rigel betelgeuse polaris) <CR) 


This expression requires a carriage return at the end of the line before any 
action is taken. The first function, RATOM, requires a carriage return before it 
receives its input even though that input is already in the buffer. 

Alternatively, if you typed in 


<— (PROGN 
(READ) 
(READ) ) 
(rigel betelgeuse polaris) 


with the same input sequence except for the (CR), no carriage return is required 
because READ will accept the next atom (see Section 14.1). 

INTERLISP provides you with a substantial amount of control over line 
buffering. Many application programs need to get their data in certain se- 
quences or ensure that all of the data are entered before they begin to process it. 
This section describes how to control line buffering. 

Note that the following functions discuss terminal tables, which are de- 
scribed in more detail in Section 15.5. 


14.6.1 Enabling and Disabling Line Buffering 
You may enable or disable line buffering by executing CONTROL, which takes 
the form 

Function: CONTROL 

# Arguments: 2 


Arguments: 1) a control mode, MODE 
2) a terminal table address, TTBL 


Value: The previous control setting. 


If MODE is T, line buffering is disabled for the specified terminal table. 
Line buffering will not be effected until TTBL is made the current terminal table 
via SETTERMTABLE (unless it already is the current terminal table—when 
TTBL is NIL). Normally, CONTROL is invoked with TTBL equal to NIL. 
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The current control mode may be obtained by executing GETCONTROL 
with a terminal table address, TTBL. GETCONTROL takes the following form: 


Function: GETCONTROL 

# Arguments: 1 

Argument: 1) a terminal table address, TTBL 
Value: The current control mode for TTBL. 


Consider the following example, 


+ (GETCONTROL) 
NIL 


<—(SETQ NEW.TTBL (COPYTERMTABLE) ) 
[TERMTABLEP]#1, 104640 


«(CONTROL T NEW.TTBL) 
NIL 


+ (GETCONTROL NEW.TTBL) 
T 


When line buffering is disabled, the function initiating input determines 
how the typed-in characters are treated when (CONTROL T) is in effect. There 
are several cases: 


READ 
If the input sequence is a list (determined by a leading "("' or "[''), then the input 
is buffered until a carriage return or matching closing parenthesis or bracket is 
detected. That is, the effect is the same as if CONTROL is NIL. 

If the input sequence is not a list, a break character or a separator character 
terminates the character sequence and causes it to be transferred to the reques- 
tor. CTRL-A and CTRL-Q are both operable, but only on the most recent atom. 


(DEFINEQ 
(read.without.buffering (ttb1) 
(PROG (line chars) 
(CONTROL T ttb1) 
(SETQ line NIL) 
loop 
(SETQ chars (READ) ) 
(COND 
((NULL chars) 
(PROGN 
(CONTROL NIL ttb1) 
(RETURN line) )) 
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((NULL line) 
(SETQ line (LIST chars) )) 


(T 
(SETQ line 
(APPEND line (LIST 
chars) )))) 
(GO loop) ) 


)) 


Now, let us execute this function: 


« (READ.WITHOUT.BUFFERING NIL) 
Every goode good boy deserves flavour favor <CR) 
tT 
CTRL-Q CTRL-Q 


returns: Every good boy deserves favor 


Note that CTRL-Q only deletes the last character sequence that was entered 
because each sequence separated by a blank is transmitted to READ. 


RATOM 
A sequence of characters is returned as soon as a break or separator character is 
typed in. Until that time, CTRL-A and CTRL-Q have their usual effect. 


(CONTROL T) 
NIL 

<— (RATOM) 
(<CTRL-A) ## 


returns ( because ( is a break character. It would already have been transmitted. 
## indicates that CTRL-A was typed in while the buffer was empty. 


READC/PEEKC 
A character is transmitted immediately. No line editing is possible. 


«(CONTROL T) 

NIL 

< (READC) « CTRL-A) 
«space) 


because CTRL-A forces READC to return NIL, so the result is the null character 
code. 
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14.6.2 Clearing the Line Buffer 


CLEARBUF clears the line buffer for a file from which a program is reading. It 
takes the form 


Function: CLEARBUF 

# Arguments: 2 

Arguments: 1) a file name, FILE 
2) a flag, FLAG 

Value: NIL 


Input is buffered for every from file from which INTERLISP can read. Usu- 
ally, a program reading from the terminal discovers that the user has entered 
some erroneous expression. At that point, rather than process the expression, it 
clears the line buffer and prints a warning message or otherwise handles the 
error. To clear the terminal line buffer, the program merely executes 


<(CLEARBUF T T) 
NIL 


This form of CLEARBUF saves both the line buffer and the system buffer 
for later access by the program. However, if both the line buffer and the system 
buffer are empty, nothing is stored into the internal save buffers. 

Certain control characters also save the line and system buffers. CTRL-D, 
CTRL-E, CTRL-H, CTRL-P, and CTRL-S cause INTERLISP to automatically 
perform (CLEARBUG T T). After the user has finished his interaction with 
CTRL-P or CTRL-S, the line and system buffers are restored. 


14.6.3 Accessing the Buffer’s Contents 


After the line and system buffers are saved, you may access their contents by 
executing either LINBUF or SYSBUF. They take the form 


Function: LINBUF 
SYSBUF 
# Arguments: 1 
Arguments: 1) a flag, FLAG 
Value: The contents of the internal save buffer. 


If FLAG is T, the contents of the line buffer or the system buffer are re- 
turned to the user from the internal save buffers. If FLAG is NIL, the respective 
internal buffer will be cleared. 
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14.6.4 Resetting the Line and System Buffers 


After you have cleared the line and system buffers, you may reset them to their 
original contents or some modified version of their contents before processing 
the input. Two functions, BKLINBUF and BKSYSBUF set the line and system 
buffers, respectively, to the values of their arguments. BKSYSBUF takes the 
form 


Function: BKSYSBUF 
# Arguments: 3 


Argument: 1) a string, X 
2) a flag, FLAG 
3) a read table, RDTBL 


Value: The PRINi-name of X. 


BKSYSBUF set the buffer to the PRIN1-name of X. If the length of the 
string is greater than 160 characters, only the first 160 characters will be re- 
stored. 

Consider the following examples: 


<(BKSYSBUF '(ADD1 1)"’) 
"(ADD1 1)" 


«(ADD1 1) 
2 


«(BKLINBUF ''I love New York") 
"T love New York"! 


+ (BKSYSBUF '"'(SETQ x (READ) )'') 
"(SETQ x (READ) )" 


which causes the following to appear in the system buffer to be evaluated: 
<(SETQ x (READ) ) 
tT 
cursor waits for you to enter something, for example 
(I love New York) 
(I love New York) 
BKLINBUF takes the form 


Function: BKLINBUF 
# Arguments: 1 
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Argument: 1) a string, STRING 
Value: The value of STRING. 


BKLINBUF sets the INTERLISP line buffer to the value of STRING. The 
length of the line buffer may be limited in certain implementations by the host 
computer operating system, in which case the extra characters are ignored. 


14.7 THE ASKUSER PACKAGE 


Many programs engage in an interactive dialogue with a user before, during, 
and after execution of their primary functions. To facilitate the construction of 
dialogues and interpretation of the responses, INTERLISP provides the Askuser 
Package. 

Askuser is driven by a key list, a list of expressions that describe 


what may be entered by the user, 
what responses should be given to the user, 
what result should be returned to the calling function. 


14.7.1 ASKUSER 


ASKUSER allows yoyr program to conduct an interactive dialogue with a user 
to acquire information about what it should do next. It takes the form 


Function: ASKUSER 
# Arguments: 8 


Arguments: 1) a time period, WAIT 
a default answer, DEFAULT 
3) a message, MESSAGE 
a key list, KEYLST 
a type ahead flag, TYPEAHEAD 
a LISPX flag, LISPXPRINTFLAG 
7) an options list, OPTIONSLST 


8) a file name, FILE 


Value: As described below. 


ASKUSER displays MESSAGE at the terminal (unless FILE is non-NIL). It 
then issues a READC to get a character from type in. As each character is typed, 
it is matched against the keys in KEYLST. If a match is successful, the character 
(or its replacement) is echoed or a new prompt is displayed as determined by the 
options. If matching is unsuccessful, the character is deemed unacceptable (un- 
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less it appears ina MACROCHARS entry) and ASKUSER rings the bell or oth- 
erwise signals you. 


<(ASKUSER 100 '(N NO) "DO YOU WANT TO CONTINUE?" '(Y N)) 
N 


N "returned by ASKUSER" 


At any time, you may type ?. ASKUSER will display a list of acceptable 
responses either drawn from the key list entries or as determined by EXPLAIN- 
STRING if it appears in OPTIONSLST. You may also type one of several con- 
trol characters (CTRL-A, CTRL-Q, CTRL-X) which will cause ASKUSER to 
reinitialize and begin anew. 


<—(ASKUSER NIL 
' (RED) 
"WHAT IS YOUR FAVORITE COLOR?" 
"(RED BLUE ORANGE GREEN YELLOW PURPLE) ) 
»’ 2 
one of: 
RED 
BLUE 
ORANGE 
GREEN 
YELLOW 
PURPLE 


Keys may be atoms or strings. Thus, ASKUSER will not return a value until 
you have entered an acceptable response. 

ASKUSER waits for WAIT seconds after printing MESSAGE. If WAIT is 
NIL, ASKUSER will wait forever. If the waiting period expires with no user type 
in, ASKUSER supplies the default response given by DEFAULT after printing 
't...", DEFAULT must be one of the keys in KEYLST. It is treated exactly as if it 
had been entered from the keyboard. Typically, N or NO is used as the value of 
DEFAULT. 

KEYLST is a key list (as described in Section 14.7.2), OPTIONSLST allows 
you to define a global set of options for ASKUSER rather than associating op- 
tions with each key entry. 

If you want to type ahead, then TYPEAHEAD should be T. Otherwise, 
characters typed in ahead of ASKUSER are cleared and saved. 

LISPXPRINTFLAG determines whether or not the interaction is recorded 
on the history list (see Chapter 27). 

If FILE is non-NIL, characters are read from the file until an unacceptable 
input is encountered or a key is complete. FILE may be either a file name or a 
string. If it is a string, and all its characters are read without completing a key, 
FILE is reset to T and interaction continues with the user via type in. 
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14.7.2 Key Completion 


ASKUSER attempts to match characters that it reads until it completes a key. 
Deciding if a key is complete is more complex than whether or not all of its 
characters have been matched. There may be multiple keys with characters in 
corresponding positions that would match the most recently read character. 
ASKUSER would not know which key to match without reading additional 
characters. 

. A key is considered complete after N characters have been read if 


1. All of its characters have been matched and no other key has the key as a 
substring. 


2. All of its characters have been matched and you have entered a confirma- 
tion character. The confirmation character serves both to complete the 
key and confirm it even when CONFIRMELG is NIL. 


This allows you to complete a key through confirmation when the key is a 
substring of another key, even when CONFIRMEFLG is NIL. The confirming 
character serves to both complete the key and confirm it. 


3. All ofits characters have been matched, and CONFIRMFLG is NIL, and 
the KEYLST option has a value, then if the next characters matches one 
of the keys in the value of the KEYLST option. 


The IRM suggests the following example: 


(ST "ore and redefine " 
CONFIRMFLG T 
KEYLST ('"'' (F . "orget exprs'')) 


Suppose there was another key that was STX. If you had typed ST, then 
there are still two ways to complete the key. Typing F completes the ST 
key because’ it matches the F of the inner key list. 


4. There is only one key left and you have typed a confirming character. If 
CONFIRMELG is T, you must still confirm a key whether or not it is 
complete. Confirmation allows you to complete a key even though you 
have not entered all of the required characters. 


14.7.3 Key List Format 
A key list is a list of expressions that drive the actions of ASKUSER. A key list 
takes the form 

(<key) <promptstring) <options)) 


where: (key) is an atom or a string. 
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{promptstring) is an atom or string that 
is printed when the key is 
recognized. 

<options) is a list of options. 


Options may be specified in two ways: 


1. If an option appears in (options), its value is the next element in the list. 
That is, (options) has a property list format. 


2. If the option appears in OPTIONSLST, its value is the next element in 
OPTIONSLST. OPTIONSLST serves as a default for the entire key list 
which may have several levels of structure. 


If an option does not appear on (options) or OPTIONSLST, its value is 
assumed NIL for this invocation of ASKUSERS. 


14.7.4 The Default Key List 


If ASKUSER is called with KEYLST having the value NIL, it uses a default key 
list. The structure of this key list is 


((Y "es<er)'') (N "o¢er)>")) 


<(ASKUSER NIL 'N "Type ? for Responses'') 
Type ? for Responses 

<7 

Yes 

No 


4 


All other inputs are unacceptable. ASKUSER signals this fact by ringing 
the bell (or sounding some other terminal chime). It does not echo the erroneous 


character. 


14.7.5 Key List Options 


The following options may occur in the key list (options) segment or in OP- 
TIONSLST: 


CONFIRMFLG If this flag is T, the key must 
be confirmed by typing a <cr) or 
a space after the last 
character. If its value is a 
list, the confirmation character 
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may be any member of the list 
(in addition to <cr) and 
<space)). 


<—(ASKUSER NIL 
'N 
"Do You Like Ice Cream?'"! 
"(( Y Neg!) (N Mot) (M "aybe!') ) 
NIL 
NIL 
'(CONFIRMFLG T) ) 
Do You Like Ice Cream? 
Yes<CR) 
Y 


where the ‘‘es” was printed by ASKUSER. Then, I had to terminate the input 
with a (CR) because the CONFIRMFLG had the value T. 


PROMPTCONFIRMFLG If T, whenever confirmation is 
required, you will be prompted 
with the message "[confirm]". 


For example, let us modify the options list above to add (PROMPTCON- 
FIRMFLG T): 


<(ASKUSER NIL 
'N 
"Do You Like Ice Cream?" 
"(( v Neg!) (N No!t) (M "Naybe!') ) 
NIL 
NIL 
'(CONFIRMFLG T PROMPTCONFIRMFLG T) ) 
Do You Like Ice Cream? 
Yes [confirm] <CR) 


Y 

PROMPTON If non-NIL, the PROMPTSTRING 
will be printed only when. the 
key is confirmed with a member 
of its value. 

COMPLETEON When a confirming character is 


read, the value of this option 
is used to automatically 
complete the key. These 
characters are printed only when 
the key is confirmed by a member 
of PROMPTON. 
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Let us modify the example above to demonstrate these features: 


“—(ASKUSER NIL 


'N 
"Do You Like Ice Cream?" 
'(( Y "es, if you really like it.'’) 
(N "o, if you don't like it.'') 
(M "aybe, if you are not sure!'')) 
NIL 
NIL 
'(CONFIRMFLG ($) PROMPTON ($) COMPLETEON ($))) 


Do You Like Ice Cream? 
Y$es, if you really like it. 


iy 


where the $ is entered by the user, and the remaining characters are used to 
complete the answer. 


NOCASEFLG 


NOECHOFLG 


If T, case-independent matching 
is not performed; otherwise, 
characters typed in must match 
the case of characters in the 
key. 


If non-NIL, matched characters 
are not echoed. Also, the 
confirming character will not be 
echoed. 


AUTOCOMPLETEFLG If non-NIL, ASKUSER attempts to 


complete the key after each 
character is typed rather than 
waiting for the entire key to be 
entered. ASKUSER will only 
attempt to complete an 
unambiguous key. 


<(ASKUSER NIL 


'N 

"Do You Like Ice Cream?" 

'(( YES ", if you really like it.") 
(NO '', if you don't like it.") 
(MAYB ', if you are not sure!"')) 

NIL 

NIL 

' (CONFIRMFLG ($) AUTOCOMPLETEFLG T)) 


Do You Like Ice Cream? 
YES, if you really like it.<CR) 


YES 
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Note that the key was completed automatically once I typed the Y via 


ASKUSER printing “ES, if you really like it.” and then waiting for me to termi- 
nate input. 


RETURN If non-NIL, its value is 
evaluated and returned as the 
value of executing ASKUSER. 
Different keys may have 
different return values. 


(ASKUSER NIL 
'N 
"Do You. Like Ice Cream?"! 
'(( YES ", if you really like it."’) 
(NO ", if you don't like it.") 
(MAYB ", if you are not sure!'')) 
NIL 
NIL 
'(CONFIRMFLG T 
AUTOCOMPLETEFLG T 
RETURN 'CHOCOLATE) ) 
Do You Like Ice Cream? 
YES, if you really like it.<CR) 
CHOCOLATE 


EXPLAINSTRING If non-NIL, its value is printed 
when a user types a ? while 
ASKUSER expects a key. Normally, 
ASKUSER will display the 
possible key values in response 
to a ?. Using EXPLAINSTRING, you 
may provide detailed 
explanations of what is expected 
to the user. 


KEYSTRING If non-NIL, matched characters 
in the key are echoed by the 
corresponding characters in 
KEYSTRING. Its primary use is 
for echoing lower-case 
characters. 


MACROCHARS Its value is a list of detailed 
pairs of the form 


(<character) . <expression)) 





EXPLAINDELIMITER 


14.7.6 Key List Construction 


14.7 The ASKUSER Package 443 


If a character that has been 
typed in does not match any of 
the keys, but does occur in a 
MACROCHAR entry, the expression 
is evaluated. This implements a 
read macro capability inside 
ASKUSER. 


If non-NIL, its value is printed 
to separate the explanation from 
?. Initially, its value is (cr). 
You may set it to any character 
or combination of characters 
represented as a string. 


Key list construction can be simplified when you do not want to provide prompt 
strings or options for key entries. MAKEKEYLST constructs a simple key list 


for you. It takes the form 


Function: MAKEKEYLST 


# Arguments: 3 


Arguments: 1) a list of keys, LST 
2) a default key, DEFAULTKEY 
3) a lower-case flag, LCASEFLG 


Value: The selected key. 


MAKEKEYLST takes a list of atoms or strings, LST, and constructs a key 
list. DEFAULTKEY, if non NIL, is the last key in the key list. It permits you to 
specify ‘‘none of the above” conditions. Otherwise, a key which permits you to 
specify “‘No”’ is included in the key list. If LCASEFLG is T, keys represented as 
upper case in the key list will be echoed in lower case. 

You may specify a selection by typing the characters of a key or a number 
corresponding to its position in the key list. Consider the following example: 


«(MAKEKEYLST '(CONNECT PRINT LOAD MAKE) 'NO T) 


((CONNECT NIL 


KEYSTRING "CONNECT" 


CONFIRMFLG T 


AUTOCOMPLETEFLG NIL 


RETURN 


(PRINT NIL 


"CONNECT 


KEYSTRING ''PRINT" 
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(LOAD 


(MAKE 


CONFIRMFLG T 
AUTOCOMPLETEFLG NIL 
RETURN 'LOAD) 

NIL 

KEYSTRING "LOAD" 
CONFIRMFLG T 
AUTOCOMPLETEFLG NIL 
RETURN 'LOAD) 

NIL 

KEYSTRING ''MAKE" 
CONFIRMFLG T 
AUTOCOMPLETEFLG NIL 
RETURN 'MAKE) 


(1 "CONNECT'' NOECHOFLG T 


EXPLAINSTRING '1-CONNECT"' 

CONFIRMFLG T 

RETURN (PROGN 

. (TERPRI T) 
'CONNECT) ) 


("'No-none of the abovel!'" '" 


CONFIRMFLG T 
AUTCOMPLETEFLG T 
RETURN NIL) ) 


14.7.7 Special Keys 


ASKUSER allows you to use a few symbols to have special meaning in the key 
list. These include 


& 


$$ 


<list) 


This symbol can be used as a key that will 
match any single character, provided the 
character does not match with some other key at 
that level. 


This symbol can be used as a key to match with 
the result of a single invocation of READ. $ 
allows you to have a READ that is errorset 
protected within ASKUSER, so that CTRL-E will 
allow you to erase the last character and 
continue with another key. 


This symbol can be used as a key to match a 
Single invocation of READLINE. 


The <list>) is evaluated as an expression. Its 
value is used to match the key. This allows you 





mor 
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to provide for arbitrary input operations for 
any ASKUSER request. That is, besides the 
standard keys, you may also allow a user to 
enter other commands that are outside the 
purview of the current sequence. 


The empty string can be used as a key. Because 
it has no characters, all of its characters are 
automatically matched. It usually is used as a 
place marker. The IRM notes that one of the 
entries on the key list for ADDTOFILES? appears 
as 


("1 "Pile/List: " 


EXPLAINSTRING "a file name or name of a function 


KEYLST ($)) 


Thus, if you type a character that does not 
match any of the other characters in the key 
list, the character completes the " ' key 
because it matches with the $ in the inner key 
list. 





ibe 
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The corollary to entering data into a program is to emit data from it. There are 
two aspects to this ability: 


1. To present data, possibly formatted, in such a way that it is both read- 
able and understandable by the program user. 


2. To preserve data on an external file system such that its lifetime exceeds 
the execution of the program. 


This chapter discusses the output functions provided by INTERLISP. Most 
functions work equally well whether the output is directed to the terminal (de- 
fault) or to an external file (specified by an optional argument). Exceptions will 
be noted in the text. 

Many of the functions discussed below will take an optional argument which 
is a file name. If this argument is not present, output is directed to the terminal. 
If it is present and the file is open for output, the output will be directed to the 
file. Some of the functions also take a read table as an argument. This will en- 
sure that data written out may be read in properly under control of the same read 
table. 

INTERLISP will print out the contents of standard objects such as atoms, 
lists, strings, and numbers. Other objects are printed in the form 


[<datatype) ]#( address) 
where (datatype) is the type of object, such as ARRAY, and (address) is its 


location in memory. To display the contents of these objects, you must use DEF- 
PRINT to specify functions that know how to print specific objects. 
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15.1 PRINTING S-EXPRESSIONS: PRINX 


INTERLISP programs manipulate S-expressions be they atoms or lists. The ba- 
sic output facility provides for the display of S-expressions. Indeed, most of the 
display from your programs will be in the form of S-expressions. Three functions 
can support the bulk of your printing requirements. The effect of some of these 
functions may be mediated by a read table. 


15.1.1 PRIN1 


PRINI is a function that prints the value of its first argument. An optional sec- 
ond argument may specify an external file. Its format is 


Function: PRIN1L 
PRIN3 

# Arguments: 1-2 

Arguments: 1) an S-expression, EXPRESSION 
2) a file name (optional), FILE 


Value: The value of the S-expression. 


PRINI1 prints the value of EXPRESSION on the specified file. If file is not 
specified, the primary output file (see Section 16.2) will be used. In most cases, 
this will be your terminal. 


<—(SETQ fruit 'orange) 
orange 


«(PRIN1 fruit) 
orange 


«-(PRIN1 ''database engineering") 
database engineering 


Note that PRIN1 prints the contents of the string without its enclosing dou- 
ble-quotes. 


<(SETQ presidents 
(APPEND (LIST 'kennedy 'johnson) 
(LIST 'nixon 'ford))) 
(kennedy johnson nixon ford) 


«(PRIN1 presidents) 
(kennedy johnson nixon ford) 


PRINI1’s actions are not mediated by a read table. Thus, it is primarily used 
for printing formatting characters. 
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«(PRIN1 '%[) 
[ enables us to print a left square bracket 


<(PRIN1 100) 
100 


«(RADIX 8) 
12 


<(PRIN1 100) 
144 


Note the change in radix affects the resulting output. 

If the value of the argument is something other than an atom, number, list, 
or string, PRIN1 will print the value of the pointer to the INTERLISP object. 
The pointer describes the storage location of the object. 


«(PRIN1 (ARRAY 10)) 
{ ARRAYP }#542224 


PRIN3 is a variant of PRIN1 that does not increment the position counter 
for the output line. It may be used to place control characters in the output 
buffer. No line length checks are performed when PRIN3 is used. 


15.1.2 Printing with Separators 
PRIN2 prints S-expressions on a file such that they may be properly read back 
into the program by READ using a read table. The format for PRIN2 is 


Function: PRIN2 
PRIN4 
SHOWPRIN2 


# Arguments: 1-3 


Arguments: 1) an S-expression, EXPRESSION 
2) a file name (optional), FILE 
3) a read table (optional), RDTBL 


Value: The value of the S-expression. 


PRIN2 prints all break and separator characters in the S-expression. Con- 
trast the printing of strings by PRIN2 with that of PRIN1: 


«(PRIN2 "database engineering") 
"database engineering" 


where “‘ is a break character that denotes a string. 
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“(PRIN2 '4[) 
%[ where % is the escape character. 


+-(PRIN2 100) 
100 


«(RADIX 8) 
12 


«(PRIN2 100) 
144Q 


Note that PRIN2 inserts a Q after the number when the radix has been 
changed while PRIN1 does not. Both functions will print the number in octal. 

PRIN2 is used for printing S-expressions to a file that may be read back into 
INTERLISP via READ. It is used by most of the File Package functions for 
printing various types of S-expressions to a file. The break and separator charac- 
ters are preceded by % (the escape character) so that they are read back in prop- 
erly. 

If the value of the argument is something other than an atom, number, list, 
or string, PRIN2 will print the value of the pointer to the INTERLISP object 
exactly like PRIN1. The pointer describes the datatype and storage location of 
the object. 

PRIN4 is a variant of PRIN2 that does not increment the position counter 
for the output line. It may be used to place control characters in the output 
buffer. No line length checks are performed when PRIN4 is used. . 

SHOWPRIN2 acts like PRIN2 except that its prettyprints the value of the S- 
expression. Prettyprinting (see Section 15.7) is enabled by setting SYSPRET- 
TYFLG to T. Initially, the value of SYSPRETTYFLG is NIL. 


A Definition of SHOWPRINT 
We might define SHOWPRIN2 as follows: 


(DEFINEQ 
(showprin2 (expression file rdtbl) 
(COND 
(SYSPRETTYFLG 
(* 
If the system prettyprint flag is 
set, the value of the flag may be the 
function to be used to perform the 
prettyprinting operation. 


Otherwise, we just use PRINTDEF, 
which is the standard prettyprinting 
function. 
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(RESETFORM (OUTPUT FILE) 


(APPLY* 
(COND 
((GETD SYSPRETTYFLG) 
SYSPRETTYFLG) 
(T 'PRINTDEF) ) 
expression 
T))) 
(T 
(* 
Otherwise, just use PRIN2 to do the 
job as the user intended. 
) 
(PRIN2 expression file rdtbl))) 
expression 


)) 


15.1.3 Printing with a Carriage Return 


Neither PRIN1 nor PRIN2 terminates the output line after printing the value of 
the S-expression. To do so, you must explicitly execute (TERPRI) to place a 
carriage return in the output buffer. However, using PRINT, you may combine 
the effects of both PRIN2 and TERPRI in one function. PRINT takes the format 


Function: PRINT 
SHOWPRINT 
# Arguments: 1-3 


Arguments: 1) an S-expression, EXPRESSION 
2) a file name (optional), FILE 
3) a read table (optional), RDTBL 


Value: The value of the S-expression. 


PRINT uses PRIN2 to display the value of the S-expression and then places 
a carriage return in the output buffer. 


«-(PRIN2 (ARRAY 10)) 
{ ARRAYP }#542254{ ARRAYP }#542254 


«(PRINT (ARRAY 10)) 
{ ARRAYP }#542240 
{ ARRAYP }#542240 


In the first example, PRIN2 does not insert a (CR), so the value printed and 
the value returned by the function appear on the same line. In the second exam- 
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ple, PRINT has placed a (CR) after the object pointer. Note that INTERLISP 
automatically inserts a line feed after a carriage return in the output buffer. 

SHOWPRINT acts like PRINT except that it prettyprints the value of the S- 
expression. Prettyprinting (see Section 15.7) is enabled if SYSPRETTYFLG has 
the value T. Initially, SYSPRETTYFLG is NIL. 


15.1.4 Printing Bells 


Most users now interact with computer systems via video display units (VDUs) 
which are, for the most part, silent. Sometimes, the system or a program that 
you have written will want to catch your attention. It can do so by printing a 
sequence of bells via PRINTBELLS, which takes the form 


Function: PRINTBELLS 

# Arguments: 0 

Argument: NIL 

Value: " ™ (e.g., a string with non-printing bell 


character codes). c 

PRINTBELLS is an anachronism remaining from the early days of comput- 
ing when most interactive usage was performed with Teletypes or similar de- 
vices. These devices had a physical bell which rang when you reached the end of 
the carriage on the printer. The bell could be sounded by a program by sending 
the appropriate character code to the device (e.g., hexadecimal 2F for an IBM 
System/370 machine). Today, most VDUs have an audible signal (not necessar- 
ily a bell) which performs the same function. PRINTBELLS sends a sequence of 
character codes to the device that result in the audible signal being produced by 
the device. 


15.1.5 User Defined Printing 


As noted above, the printing routines will only print the values of LISP objects 
which are atoms, numbers, strings, or lists. Other LISP objects are normally 
represented by pointers to their storage locations. You may provide your own 
printing routines to handle other types of LISP objects via DEFPRINT, which 
takes the form 


Function: DEFPRINT 
# Arguments: 2 


Arguments: 1) an INTERLISP object type, TYPE 
2) a function, FN 


Value: oi 
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TYPE is either a type name, such as ARRAYP, TERMTABLEP, etc., or a 
type number. 

DEFPRINT specifies a function that will handle the printing of LISP ob- 
jects of the specified type. Whenever a LISP object of TYPE is encountered by 
one of the printing routines, it calls FN with the LISP object as its argument. 
The function must be defined in the normal manner using DEFINE or DE- 
FINEQ. 

FN may do one of three things: 


1. It may return NIL, whence the object will be printed using the system 
default. 


2. It may print the object according to your specifications in the code. It 
should return (NIL) to prevent any further action by the calling routine. 

3. It may return a specification for how the object is to be printed. This 
specification takes the form 


(<item1) . <item2)) 


ITEM1 will be printed using PRIN1 unless it is NIL, whence no action will oc- 
cur. ITEM? is then printed using PRIN2 with no intervening spaces between the 
two items. The IRM notes that ITEMI1 will typically be a READMACRO char- 
acter. 

Consider a function for printing an array of numbers. We would like to print 
the elements of an array as a list each of whose elements is a CONS cell. The 
CAR of the CONS cell is the index and the CDR is the element at that location. 
Let us define PRINT.ARRAY to perform this operation. 


<— (DEFINEQ 
(print.array (x) 
(PROG (size) 
(COND 
((NOT (ARRAYP x)) 
(ERROR "Not an array" x))) 
(SETQ size (ARRAYSIZE x)) 
(FOR I FROM 1 to SIZE 
DO 
(PRINT (CONS I (ELT x I))))) 
)) 
(PRINT. ARRAY) 


<-(DEFPRINT 'ARRAYP (FUNCTION PRINT. ARRAY) ) 
T 


<(SETQ Al (ARRAY 5)) 
(1) 
(2) 
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(3) 
(4) 


(5) 
{ ARRAYP }#542674 


The effect of DEFPRINT is immediate once the function is defined to IN- 
TERLISP. 

Note that each of the elements is NIL so only the index appears. Now, let’s 
populate the array using the following CLISP construct. 


«-(FOR I FROM 1 TO 5 DO (SETA Al I (ITIMES I 100) )) 
NIL 


«(PRINT A1) 

(1 . 100) 

(2 . 200) 

(3 . 300) 

(4 . 400) 

(5 . 500) 

{ ARRAYP }#542674 


DEFPRINT combined with the PRINTOUT package (see Section 15.8) pro- 
vides you with considerable flexibility in formatting output of extended LISP 
objects and structures. 


15.1.6 Printing Unusual Data Structures 


Some data structures cannot be printed and read in easily. These include re- 
entrant and circular data structures. INTERLISP provides the HPRINT pack- 
age to print these data structures. HPRINT is intended for use with the File 
Package for dumping the values of variables to files so that they may later be 
reloaded. 

HPRINT will print and read back any structure containing user datatypes, 
arrays, hash tables, and unusual list structures. It does so by following all of the 
pointers to the lowest level of the structure and writing each item encountered 
during its passage. Data so written are surrounded by special read macro char- 
acters (see Section 14.4.3) to identify the unusual items in the structure when it is 
read back by INTERLISP. 

The HPRINT package provides three functions for printing, reading, and 
copying unusual data structures. These take the following formats 


Function: HPRINT 


# Arguments: 4 


Arguments: 1) an S-expression, EXPRESSION 
2) a file name, FILE 
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3) a circular list flag, UNCIRCULAR 
4) the type of data, DATATYPESEEN 


Value: NIL 


HPRINT prints the value of EXPRESSION on FILE. If UNCIRCULAR has 
the value non-NIL, HPRINT will not check for circularities in EXPRESSION. If 
you do not check for circularities in your data structures, you may miss chances 
for greater speed and more efficient use of storage. 

HPRINT is usually used to print structures to disk files. The algorithm relies 
on an ability to reset the file pointer to indicate duplicate elements in EXPRES- 
SION. If FILE is not a disk file and UNCIRCULAR is NIL, HPRINT opens a 
temporary file, HPRINT.SCRATCH, prints the expression on it, and then cop- 
ies that file to the primary output file. The temporary file is deleted. 

Consider the following example: 


<(SETQ rare-gases 
(LIST 'helium 'krypton 'argon 'xenon 'radon)) 
(helium krypton argon xenon radon) 


Let us make this list circular via the following statement: 


«-(RPLACD (LAST rare-gases) rare-gases) 
(helium krypton argon xenon radon helium krypton argon 


sa) 


which would continue to print forever. 
Now, we can print this circular list via 


«-(HPRINT rare-gases T NIL) 
(helium krypton argon xenon radon . [1]) 
NIL 


where the CDR of the last cell of the list indicates that the foregoing elements 
repeat indefinitely. 
When HPRINT sees a user datatype for the first time, it will print a sum- 
mary of that datatype’s declaration. When this is read in the datatype is rede- 
-clared. If DATATYPESEEN is non-NIL, HPRINT assumes that the same data- 
type declaration is to be used at read time that was used at print time, and does 
not print the declarations. Consider the example based on complex numbers (see 
Section 13.7.2): 


<(SETQ x (COMPLEX 1.0 3.0)) 
(C450): 6 350), because we already have a DEFPRINT 
declaration in force 
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<(HPRINT x T NIL NIL) 
{$COMPLEX (FLOATP FLOATP) 1.0 3.0] 
«(HPRINT x T NIL T) 
{COMPLEX 1.0 3.0) 


To invoke HPRINT from the File Package, you may use the file package 
commands HORRIBLEVARS and UGLYVARS (see Section 17.2.2). 


Reading Unusual Data Structures 
The corresponding function for reading an unusual data structure is HREAD. It 
takes the form 


Function: HREAD 


# Arguments: 1 
Arguments: 1) a file name, FILE 
Value: NIL 


HREAD reads in an unusual data structure from a file. Consider the follow- 
ing example: 


«(OPENFILE 'JUNK 'OUTPUT) 
{KAISLER) JUNK. .1 


«(HPRINT x 'JUNK NIL NIL) 
NIL 


«-(CLOSEF 'JUNK) 
{KAISLER) JUNK. .1 


Now, we can read the contents of the file using READFILE to see what has 
been printed out: 


«-(READFILE 'JUNK) 
({$COMPLEX (FLOATP FLOATP) 1.0 3.0]) 


And, to set Y to the value in the file JUNK, we can use HREAD as follows: 
«-(OPENFILE 'JUNK 'INPUT 'OLD) 


{KAISLER) JUNK. .1 


«-(SETQ y (HREAD 'JUNK) ) 
CCI.0 33509) 


«(REAL y) 
1.0 
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«(IMAG y) 
3.0 


Copying Unusual Data Structures 


Finally, you may use the function HCOPYALL to copy an unusual data struc- 
ture. It takes the form 


Function: HCOPYALL 

# Arguments: 1 

Arguments: 1) an S-expression, EXPRESSION 
Value: The value of EXPRESSION. 


To set Z to the value of Y, we can use the expression 


<(SETQ z (HCOPYALL y)) 
(€1.0°. 340)) 


15.1.7 Writing Expressions to a File 


You may write a sequence of one or more expressions to a file using WRITE- 
FILE, which takes the form 


Function: WRITEFILE 

# Arguments: 2 

Arguments: 1) a list of one or more S-expressions, 
EXPRESSION 


2) a file name, FILE 


Value: The file name. 


WRITEFILE writes a date expression to FILE. It then writes the successive 
S-expressions that are the value of EXPRESSION to the file using FILERDTBL 
as its read table. If EXPRESSION is an atom, its value is used (for example, the 
name of a variable whose value is a list of functions). If FILE is not open, it is 
opened prior to writing. 

If FILE is a list, (CAR FILE) is used as the name of the file to be written and 
it is left open. Otherwise, the atom STOP is written to the file after the value of 
EXPRESSION and the file is closed. 

Consider the following example: 


<(OPENFILE 'TEST 'OUTPUT) 
¢(KAISLER)TEST. .1 
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+-(WRITEFILE COMPLEXCOMS 'TEST) 
{(KAISLER)TEST. .1 


Now, to check what has been written to the file, we may use READFILE (see 
Section 14.2.9). | 


*-(READFILE 'TEST) 
((PRIN1 
(QUOTE 
"WRITEFILE of <(KAISLER)TEST..1 MADE BY KAISLER 
ON 29-Jul-84 13:27:30" T) 
(FNS * COMPLEXFNS) 
(RECORDS COMPLEX) 
(P 
(DEFPRINT (QUOTE COMPLEX) (FUNCTION 
PRINT. COMPLEX) ) ) ) 


Note that READFILE does not return the atom STOP which signals the end 
of the file. 


Terminating a File 
ENDFILE merely writes STOP on the file and closes it. It takes the form 
Function: ENDFILE 
# Arguments: 1 
Argument: 1) a file name, FILE 
Value: The file name. 


If FILE is not opened for output, ENDFILE generates an error. 


15.2 PRINT CONTROL FUNCTIONS 


INTERLISP provides several functions to control the positioning of information 
in an output line. These include printing multiple spaces, tabbing, and inserting 
carriage returns. 


15.2.1 Printing Multiple Spaces 


SPACES prints N spaces from the current position counter in the output line. It 
takes the form 


Function: SPACES 
# Arguments: 2 
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1) the number of spaces, NUMBER 
2) a file name (optional), FILE 


NIL 


SPACES is subject to line length checking. The value returned by SPACES 
is NIL, so SPACES may be the last function called in a function. Assuming we 


begin in position 1: 


«(PRIN1 ''Hello,") 


«(SPACES 10) 


<—(PRIN1 ''Tom!"') 
12345678901234567890 


Tom! 


A Definition for SPACES 
A simple definition of SPACES (assuming printing is directed to the primary 
output file) might appear as 


(spaces (number) 
(COND 


((NOT (NUMBERP number) ) 
(* 
Generate an error if the 
argument is not a number. 
) 
(ERROR "Argument not a number"') 
(BREAK) ) 
((ZEROP number) 
(* 
Do nothing if zero spaces are 
requested. 
) 
NIL) 
((GREATERP number 0) 
(* 
Use a simple loop to PRIN1 the 
blank character. 


) 
(PROG (a-number) 

(SETQ a-number 0) 
LOOP 

(PRIN1 " 1") 

( AND 
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(IGREATERP a-number number) 
(RETURN) ) 
(SETQ a-number (ADD1 a-number) ) 
; (GO LOOP) ))) 


5.2.2 Printing a Carriage Return 


PRIN1 and PRIN2 both print their results without forcing a new line. The user 
must explicitly place a carriage return in the output buffer to start a new output 
line. TERPRI, for terminate printing, places a carriage return followed by a line 
feed in the output buffer. It takes the form 


Function: TERPRI 

# Arguments: 1 

Argument: 1) a file name (optional), FILE 
Value: NIL 


Consider the following example: 


<(PRIN1 "An example of TERPRI'') 
<— (TERPRI) 


would result in output appearing as 


----------- beginning of the line 


An example of TERPRI<CR) 
{beginning of next output line) 


TERPRI may take an optional file name whence the carriage return and line 
feed are placed in the file. 


15.2.3 Tabbing 

Most formatted output requires that the program be able to specify position of 

the output line in which to place the resulting characters. TAB allows you to 

move the position cursor to the proper place in the output buffer. Its format is 
Function: TAB 


# Arguments: 1-3 
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Arguments: 1) a position, POS 
2) minimum spaces to print, MINSPACES 
3) a file name (optional), FILE 


Value: NIL 


TAB moves the position cursor in the current output line to POS. MIN- 
SPACES indicates the minimum number of spaces by which the cursor is to be 
displaced. If MINSPACES is NIL, 1 is assumed. 

If the current position plus MINSPACES is greater than POS, TAB exe- 
cutes TERPRI and then (SPACES POS). If MINSPACES is T and the current 
position is greater than POS, TAB does nothing. 

Consider the following example: 


«-(PROGN (PRIN1 "HELLO,') (TAB 25) (PRIN1 '"JERRY!"")) 


111111111122222222223 
123456789012345678901234567890 
HELLO, JERRY! 
But, consider using MINSPACES: 


«(PROGN (PRIN1 "HELLO,"') (TAB 25 20) (PRIN1 '"JERRY!") ) 


11111111112222222222 
12345678901234567890123456789 
HELLO, 

JERRY! 


because 20 plus the current position (6) yields 26, which is greater than the posi- 
tion specified for TAB. Thus, it prints a (CR)<LF) and spaces to the proper 
position on the following line. 


A Definition for TAB 
We might define TAB as follows: 


(DEFINEQ 
(tab (pos minspaces file) 
(PROG (posit) 
(* 
Determine character position in the 
current line of the file. 


) 
(SETQ posit (POSITION file)) 
(SPACES 

(COND 
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( (IGREATERP 
oe posit (OR minspaces 
1)) 


pos) 
(* 
If the current 
position plus 
MINSPACES is greater 
than the position to 
tab to, move to the 
next output line. 
(TERPRI file) 


pos) 
(T 

(* 
Otherwise, just move 
the requisite number 
of positions. 

(IDIFFERENCE pos x))) 

file) ) 


)) 


15.3 SETTING THE PRINT LEVEL 


Printing functions are affected by an internal parameter that determines the 
level to which lists are to be displayed on the terminal. This parameter is set by 
PRINTLEVEL, whose format is 


Function: PRINTLEVEL 
# Arguments: 2 


Arguments: 1) CAR print level value, CARLVL 
2) CDR print level value, CDRLVL 


Value: The previous parameter values for print 
level. 


The print level parameter determines how much of a list is displayed at the 
terminal when one of the printing functions is executed. The CAR print level 
controls the number of unpaired left parentheses that will be printed. Below that 
level, all lists are denoted by the symbol &. The CDR print level controls the 
number of list elements that will be printed. Remaining elements are indicated 
by -- followed by a right parenthesis. In effect, list printing is truncated. Initial 
values for the CAR and CDR print levels are 1000 and —1, respectively. 
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Consider the following examples: 


+(SETQ SYSPRETTYFLG 'T) 


NIL 
<-(SETQ states 
"(maryland 
(ohio idaho 
(virginia 
(new-york texas) 
maine) 
oregon) 
iowa) ) 


(maryland (ohio idaho (virginia (new-york texas) maine) 
oregon) iowa) 


With the inital setting, where 1000 implies a (virtually) infinite print level, 
SHOWPRINT displays the following output: 


«-(SHOWPRINT states) 
(maryland (ohio idaho (virginia (new-york texas) maine) 
oregon) iowa) 


Now, let us set the print level for CAR to 2: 
«-(PRINTLEVEL (CONS 2 -1)) 
(1000 . -1) 


«-(SHOWPRINT states) 
(maryland (ohio idaho & oregon) iowa) 


«-(PRINTLEVEL (CONS 2 2)) 
(2 . -1) 


«-(SHOWPRINT states) 
(maryland (ohio --) --) 


«-(PRINTLEVEL (CONS 0 0)) 
& 


because the print level also affects system output. 


<-(SHOWPRINT states) 
& 


You may change the CAR and CDR print levels independently by executing 


(PRINTLEVEL n NIL) change CAR print level 
(PRINTLEVEL NIL n) change CDR print level 
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If the CAR print level is negative, a carriage return will be inserted between 
all occurrences of a right parenthesis immediately followed by a left parenthesis. 


<-(SETQ fruits '(orange (apple lime) (lemon grape) ) ) 
(orange (apple lime) (lemon grape) ) 


«-(PRINTLEVEL -2 NIL) 
(1000 . -1) 


(PRINT fruits) 
(orange (apple lime) 
(lemon grape) ) 


If the CDR print level is negative, then actions concerning CDR printing are 
disabled, i.e., lists will be printed in their entirety. 

PRINTLEVEL normally affects only terminal output. Usually, output to 
other files acts as though an infinite print level existed. You may force print 
levels to be applied to file output other than the terminal by setting PLVLFILE- 
FLG to T. Initially, PLVLFILEFLG has the value NIL. 


Dynamically Setting the Print Level 

If some of your functions are particularly long, you may wish to shorten the 

printing cycle by redefining the print level. To do so while a function is printing, 

you must type CTRL-P followed by a number which is terminated by a period or 

an exclamation point. The CAR print level is immediately set to this number. 
When a CTRL-P is typed, it causes an interrupt to INTERLISP. IN- 

TERLISP immediately takes the following steps: 


1. Saves and clears the input buffer 

2. Clears the output buffer 

3. Rings the bell (see PRINTBELLS) to notify you that it has seen the 
CTRL-P 

4. Waits until you enter a number for the new print level 

5. Restores the input buffer 

6. Continues printing 


Upon return from the CTRL-P, the print level may have been changed. If 
the expression being printed is currently at a deeper level than the new print 
level, all unfinished lists are terminated by ''--)"'. You may terminate a particu- 
larly long expression by typing CTRL-P 0. 

If the number following the CTRL-P is followed by a comma, you may then 
type another number which specifies the new value of the CDR print level. 

The period terminating the CTRL-P input indicates that the print level 
should be returned to its previous setting after completing the printing of the 
current expression. Terminating the CTRL-P input with an exclamation point 
(!) causes the change to be permanent (at least, until it is changed again!). 
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15.4 PRINTING NUMBERS 


Numbers, like other atoms, have standard print names. The display of these 
names is sensitive to the values of two variables: 


RADIX which determines the basis of 
conversion for the representation of 
numbers. 

FLTFMT which specifies the floating point 
format. 


PRINTNUM allows you to. control the formatted printing of both fixed and 
floating point numbers. PRINTNUM takes the following form: 


Function: PRINTNUM 
# Arguments: 3 


Arguments: 1) a format specification, FORMAT 
2) a number, NUMBER 
3)! a file, FILE 


Value: The print name of the number. 


Format specifications are described in the following sections. 

If NUMBER is not a number (e.g., not NUMBERP) and non-NIL, 
PRINTNUM displays the error message NON-NUMERIC ARG. If NUMBER is 
NIL, PRINTNUM uses the value of NILNUMPRINTELG to decide what to do. 
If NILNUMPRINTELG is NIL, an error is generated. Otherwise, the value of 
NILNUMPRINTELG is displayed right-justified in the field. 

If the full print name of NUMBER will not fit into the specified field, it will 
be printed in its entirety. Then, a TAB is executed to properly place the line 
position in the output file. 


15.4.1 Format Conversion 


PRINTNUM may use intrinsic operating system routines to assist in printing 
formatted numbers when the format can be specified by some sort of special 
code (e.g., INTERLISP-10 and INTERLISP/370). FORMAT is converted from 
its machine-independent list form into a sequence of codes that are used by oper- 
ating system routines to print numbers of the appropriate type. 

In most cases, your program will use a several different formats, but will use 
them repeatedly throughout its execution. Each time your program calls 
PRINTNUM, FORMAT will be converted anew. You may improve the effi- 
ciency of your program by converting the formats once and storing the resulting 
format code for usage by PRINTNUM. NUMFORMATCODE performs this 
conversion for you. It takes the form 
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Function: NUMFORMATCODE 

# Arguments: 2 

Argument: 1) a format specification, FORMAT 
2) a smashflag, SMASHFLAG 

Value: A format code for the particular operating 
system under which your INTERLISP is 
running. 


Consider the following example (from INTERLISP-10): 


+-(NUMFORMATCODE '(FIX 3 NIL T)) 
(FIX . 15033171978) 


*-(NUMFORMATCODE '(FLOAT 11 2 2)) 
(FLOAT . 721436804) 


+ (NUMFORMATCODE) 
(NIL . 10000) 


Executing NUMFORMATCODE with no arguments returns an uninitial- 
ized data element that can later be smashed into by succeeding calls. 

If SMASHFLAG is a format-code data structure, the new format code will 
be placed into that represented by SMASHFLAG rather than being allocated 
new storage. 

Note that in INTERLISP-D this function is a no-op since there is no special 
internal representation for number formats. 


15.4.2 Fixed Point Format 


The FORMAT for a fixed point number is a list structure comprising the follow- 
ing items: 


FIX An identifier specifying format type. 


{width) The number of characters comprising the 
field in which to display the number. 

« radix) The basis for numeric conversion. 

{ pad) If NIL, the field is padded with spaces. If 


T, the field is padded with "0" (zero). 


{leftflush) If NIL, the number is right-justified in 
the field. If T, the number is left- 
justified in the field with trailing apaces 
filling the field. 
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Numbers, if not FIXP, are rounded to the nearest integer. Consider the fol- 
lowing examples: 


Function Call Result 
(PRINTNUM '(FIX 2) 27) 27 
(PRINTNUM '(FIX 3 NIL T) 6) 006 
(PRINTNUM '(FIX 10 8 T) 10 0000000012 
(PRINTNUM '(FIX 6 NIL NIL T) 23) 23bbb 


where ‘b’ indicates a blank or space. 


15.4.3 Floating Point Format 


A floating point number is always printed as a decimal number. FORMAT is a 
list structure comprising the following items: 


FLOAT An identifier specifying format type. 


«width) The number of characters comprising 
the field in which to display the 
number; it must account for the 
decimal point. 


{decpart) The number of digits to the right of 
the decimal point. If NIL, <decpart) 
is assumed to be zero (e.g., no digits 
to the right of the decimal point). 


{exppart) If non-NIL, the number is printed 
using exponent notation. It specifies 
the field size of the exponent 
including E and a possible sign 
prefacing the exponent. 


{pad) If NIL, padding on the left of the 
field is with spaces; otherwise, '0' 
(zero) is used. 


« round) If non-NIL, it indicates the digit 
_ position at which rounding will take 
place. 


Consider the following examples: 


Function Call Result 
(PRINTNUM '(FLOAT 7 2) 15.375) bb15.38 
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(PRINTNUM '(FLOAT 7 2 NIL T) 15.375) 0015.37 
(PRINTNUM '(FLOAT 7 2 NIL NIL 1) 18.76) 20.00 
(PRINTNUM '(FLOAT 11 2 2) 175.34) bbbbb1.75E2 


15.4.4 Changing the Integer Radix 


The INTERLISP printing functions assume a radix (or base) of 10 for printing 
integers. You may change the radix to another base via RADIX. It takes the 
form 


Function: RADIX 

# Arguments: 1 

Argument: 1) an integer, N 
Value: The old radix. 


RADIX resets the output radix for integers to the absolute value of N. If N is 
negative, integers are interpreted by the printing routines as unsigned numbers 
(e.g., as positive numbers in an infinite precision machine). Numeric output un- 
der a negative radix varies with the implementation. Consider the following ex- 
amples (from INTERLISP-10): 


(RADIX) 
10 


«(PRINT -128) 
-128 


«(RADIX 8) 
12Q 


«(PRINT -128) 
-200Q 


«(RADIX 2) 
1000 


«(PRINT -128) 
-10000000 


«(RADIX -16) 
2 


«(PRINT -128) 


eeeeeene 
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because numeric output under a negative radix varies with implementation, and 
may be questionable in interpretation. 


15.4.5 Changing the Floating Point Output Format 


You may change the format for printing floating point numbers via FLTFMT, 
which takes the form 


Function: FLTFMT 

# Arguments: 1 

Argument: 1) a format specification, FORMAT 
Value: The current format. 


FLTFMT sets the value of the variable FLTFMT to FORMAT which is a 
specification as described in Section 15.4.3. If FORMAT has the value T, the 
default floating point format is used. To set the value of FLTFMT. (FLTFMT) 
returns the current specification without changing it. 


« (FLTFMT) 
536870912 


15.5 TERMINAL TABLES 


A terminal table is used to specify the syntax classes associated with characters 
for output operations. Terminal tables may be made device dependent to ac- 
count for the particular display features of different terminals. The system ter- 
minal table has the following values: 


CHARDELETE 2. character deletion 

LINEDELETE ug line deletion code 

RETYPE 18 retype line code 

CTRLV 2 

EOL 13 end-of-line code 

RAISE NIL do not "raise" input 

LINEDELETESTR "##"" response to line delete 
code 

1STCHDEL nom 

NTHCHDEL won 

POSTCHDEL Asi ‘oP 

EMPTYCHDEL hy 

ECHODELS? NIL 

CONTROL NIL 


0 REAL 
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iL. IGNORE 
2 IGNORE 
3 IGNORE 
4 IGNORE 
5 IGNORE 
6 IGNORE 
7 SIMULATE 
8 INDICATE 
re SIMULATE 
10 SIMULATE 
11 INDICATE 
12 INDICATE 
13 REAL 
14 IGNORE 
a INDICATE 
16 INDICATE 
17 IGNORE 
18 IGNORE 
19 INDICATE 
20 INDICATE 
i INDICATE 
22 INDICATE 
23 IGNORE 
24 IGNORE 
25 INDICATE 
26 IGNORE 
27 SIMULATE 
28 INDICATE 
29 INDICATE 
30 INDICATE 
31 SIMULATE 


The functions GETSYNTAX, SETSYNTAX, and SYNTAXP (see Section 
14.4.2) all operate with terminal tables. In general, the syntax class will define 
which type of table to use. When GETSYNTAX or SETSYNTAX are given ta- 
bles with incompatible syntax classes, they generate error messages. 


«-(GETSYNTAX 'BREAK (GETTERMTABLE) ) 
ILLEGAL READTABLE 
['TERMTABLEP]#1, 104740 


«(SETSYNTAX 52 'CHARDELETE (GETREADTABLE) ) 
ILLEGAL TERMINAL TABLE 
[READTABLEP]#112203 
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A terminal table also contains information about terminal control including 
line buffering, character echoing, and case conversion. 

Note that, unlike read tables, terminal tables cannot be passed to input or 
output functions. Consider what happens: 


“(READ 'T (GETTERMTABLE) ) 
ILLEGAL READTABLE 
[TERMTABLEP ]#1, 104740 


15.5.1 Terminal Syntax Classes 


There aré seven terminal syntax classes: 


Class Function Association 
CHARDELETE Character Deletion CTRL-A 
LINEDELETE Line Deletion CTRL-Q 
RETYPE Reprint Line CTRL-R 
CTRLV CTRL-V 
EOL End of Line CR/LF 
NONE All other characters none 


Characters are assigned to a syntax class by SETSYNTAX (see Section 
14.4.3). Assigning a character to a syntax class disables the previous character. 
That character is automatically assigned to NONE. That is, only one character 
may be assigned to the first five syntax classes mentioned above. 

CHARDELETE deletes the previous character in the input buffer when it is 
typed. Repeated uses will delete successive characters back to the beginning of 
the buffer. 

LINEDELETE deletes the current line when it is typed. It cannot be used 
repeatedly. 

WORDDELETE deletes the previous ‘‘word”’ (e.g., symbol in the input 
buffer) where ‘‘word”’ is interpreted to be a sequnce of non-separator characters. 

RETYPE causes the current line to be retyped when it is typed in. It is par- 
ticularly useful when you have made repeated character and word deletions in a 
line. 

CTRL-V causes the corresponding control character to be input when it is 
followed by the appropriate control character letter. 

EOL signals to the line buffering routine that the line has been terminated 
when it is typed in. If there is an outstanding READ or READLINE, the con- 
tents of the buffer are transferred to the program. 
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The functions GETSYNTAX, SETSYNTAX, and SYNTAXP (see Section 
14.4.2) all operate with terminal tables. In general, the syntax class will define 
which type of table to use. When GETSYNTAX or SETSYNTAX are given ta- 
bles with incompatible syntax classes, they generate error messages. 


«(GETSYNTAX 'BREAK (GETTERMTABLE) ) 
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IGNORE 
IGNORE 
IGNORE 
IGNORE 
IGNORE 
IGNORE 
SIMULATE 
INDICATE 
SIMULATE 
SIMULATE 
INDICATE 
INDICATE 
REAL 
IGNORE 
INDICATE 
INDICATE 
IGNORE 
IGNORE 
INDICATE 
INDICATE 
INDICATE 
INDICATE 
IGNORE 
IGNORE 
INDICATE 
IGNORE 
SIMULATE 
INDICATE 
INDICATE 
INDICATE 
SIMULATE 


ILLEGAL READTABLE 
[TERMTABLEP]#1, 104740 


<(SETSYNTAX 52 'CHARDELETE (GETREADTABLE) ) 


ILLEGAL TERMINAL TABLE 
[READTABLEP]#112203 
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A terminal table also contains information about terminal control including 
line buffering, character echoing, and case conversion. 

Note that, unlike read tables, terminal tables cannot be passed to input or 
output functions. Consider what happens: 


+-(READ 'T (GETTERMTABLE) ) 
ILLEGAL READTABLE 
[TERMTABLEP]#1, 104740 


15.5.1 Terminal Syntax Classes 


There aré seven terminal syntax classes: 


Class Function Association 
CHARDFLETE Character Deletion CTRL-A 
LINEDELETE Line Deletion CTRL-Q 
RETYPE Reprint Line CTRL-R 
CTRLV CTRL-V 
EOL End of Line CR/LF 
NONE All other characters none 


Characters are assigned to a syntax class by SETSYNTAX (see Section 
14.4.3). Assigning a character to a syntax class disables the previous character. 
That character is automatically assigned to NONE. That is, only one character 
may be assigned to the first five syntax classes mentioned above. 

CHARDELETE deletes the previous character in the input buffer when it is 
typed. Repeated uses will delete successive characters back to the beginning of 
the buffer. 

LINEDELETE deletes the current line when it is typed. It cannot be used 
repeatedly. 

WORDDELETE deletes the previous “‘word”’ (e.g., symbol in the input 
buffer) where ‘‘word”’ is interpreted to be a sequnce of non-separator characters. 

RETYPE causes the current line to be retyped when it is typed in. It is par- 
ticularly useful when you have made repeated character and word deletions in a 
line. 

CTRL-V causes the corresponding control character to be input when it is 
followed by the appropriate control character letter. 

EOL signals to the line buffering routine that the line has been terminated 
when it is typed in. If there is an outstanding READ or READLINE, the con- 
tents of the buffer are transferred to the program. 
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15.5.2 Establishing a Terminal Table 


You may establish a terminal table by executing SETTERMTABLE, which 
takes the form 


Function: SETTERMTABLE 

# Arguments: 1 

Argument: 1) the address of a terminal table, TTBL 

Value: The address of the previous terminal 
table. 


If TTBL is not a real terminal table, SETTERMTABLE displays the error 
message “ILLEGAL TERMINAL TABLE”. Otherwise, it sets the primary ter- 
minal table to TTBL. It returns the address of the previous terminal table. 


15.5.3 Getting a Terminal Table Address 
GETTERMTABLE obtains the address of a terminal table. It takes the form 


Function: GETTERMTABLE 

# Arguments: 1 

Argument: 1) the address of a terminal table, TTBL 
Value: TTBL, if it is a real terminal table; 


otherwise, an error message. 


If TTBL is non-NIL and represents a real terminal table, the value of GET- 
TERMTABLE is TTBL. If TTBL is not the address of a real terminal table, 
GETTERMTABLE displays the error message “ILLEGAL TERMINAL TA- 
BLE”. In this case, GETTERMTABLE serves as a predicate to determine if 
TTBL is really a terminal table. 


+ (GETTERMTABLE) 
[TERMTABLEP ]#112406 


When TTBL is NIL, GETTERMTABLE returns the address of the primary 
terminal table. This is the mode in which it is most often used. Generally, you 
will want to check if the current primary terminal table is the same as the origi- 
nal system terminal table or one you have created. 

We might define the following function to check if the current terminal table 
is equal to the original system terminal table (e.g., the one supplied with the 
SYSOUT): 
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(DEFINEQ 
(origtermtable? (ttb1) 
(EQUAL origttb1 
(COND 
((NULL ttb1) 
(GETTERMTABLE) ) 
)) (T ttb1))) 


where ORIGTTBL was set upon entry to INTERLISP at session initiation via 


(SETQ origttbl (GETTERMTABLE) ) 


15.5.4 Testing a Terminal Table 


You may test whether or not a data structure is a terminal table by executing 
TERMTABLEP, which takes the form 


Function: TERMTABLEP 

# Arguments: 1 

Argument: 1) the address of a terminal table, TTBL 
Value: TTBL, if it is a terminal table; 


otherwise, NIL. 


It returns the address if the data structure is a terminal table, otherwise 
NIL. This function may seem redundant given the effect of GETTERMTABLE 
when it is supplied with a non-NIL argument. Note that TERMTABLEP returns 
NIL if its argument is not a valid terminal table whereas GETTERMTABLE 
causes an error. 


«<-(TERMTABLEP (GETREADTABLE) ) 
NIL 


< (TERMTABLEP) 
NIL 


+-(TERMTABLEP (GETTERMTABLE) ) 
[TERMTABLEP ] #112406 


15.5.5 Copying Terminal Tables 


You may copy a terminal table in order to modify it for your own use by execut- 
ing COPYTERMTABLE, which takes the form 
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Function: COPYTERMTABLE 

# Arguments: 1 

Argument: 1) the address of a terminal table, TTBL 
Value: The address of a new terminal table. 


It returns the address of a new data structure that is a copy of the specified 
terminal table. 

If TTBL is NIL or ORIG, a copy of the original system terminal table will be 
returned. 


«<(SETQ copyttbl (COPYTERMTABLE) ) 
[ TERMTABLEP ]#543173 


COPYTERMTABLE is the only function that can create a new terminal 
table for you. Moreover, you may only modify the terminal table via the function 
SETSYNTAX. 


15.5.6 Resetting the Terminal Table 


You may reset the terminal table from another terminal table using RESET- 
TERMTABLE, which takes the form 


Function: RESETTERMTABLE 

# Arguments: 2 

Arguments: 1) the address of a terminal table, TTBL 
2) another terminal table, FROM 

Value: TTBL, if it is a terminal table. 


RESETTERMTABLE copies FROM into TTBL. FROM and TTBL may be 
NIL or real terminal tables. FROM may have the value ORIG indicating that the 
original system terminal table should be used. 


15.6 TERMINAL CONTROL 


INTERLISP provides you with several functions that allow you to control the 
display portion of your terminal. These functions control the echoing of charac- 
ters that you have typed at the keyboard. 


15.6.1 Echo Modes 


When a character is typed at the keyboard, low-level routines in the operating 
system read the character (usually via interrupts) and transfer it to the IN- 
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TERLISP terminal handler. Normal characters will be echoed immediately. 
Control characters, which are signified by pressing the CONTROL or CTRL key 
and another key simultaneously, may or may not be echoed. 

Normally, control characters will be echoed using a format specified by 
ECHOCONTROL (see below). You may disable echoing for a terminal table by 
executing ECHOMODE, which takes the form 


Function: ECHOMODE 


# Arguments: 2 


Arguments: 1) an echo flag, ECHOFLAG 
2) a terminal table address, TTBL 


Value: The previous echo mode for TTBL. 


Echoing is enabled when ECHOFLAG is T; otherwise, it is disabled. Note 
that changes in the echo mode do not take effect until the terminal table is made 
the primary terminal table (unless it is the primary terminal table). Consider the 
following example: 


<(PRINT\T\1 'HELP) 
HELPHELP 


«< (ECHOMODE NIL) 
oe 


«-HELPHELP 


even though I typed (PRIN1 ‘HELP) because the input is not echoed, since I 
turned it off for the primary terminal table. 


Obtaining the Current Echo Mode 
You may determine the current echoing mode of a terminal table by executing 
GETECHOMODE, which takes the form 


Function: GETECHOMODE 

# Arguments: 1 

Argument: 1) the address of a terminal table, TTBL 
Value: The current echo mode for the indicated 


terminal table. 
Consider the following example: 


«— (GETECHOMODE) 
T 
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where we assume the terminal table has not been changed from the original sys- 
tem terminal table. 
When TTBL is NIL, the primary terminal table is assumed: 


<(ECHOMODE NIL) 
T 


will disable echoing on the primary terminal table. 


- 15.6.2 Echo Control 


ECHOCONTROL allows you to determine how control characters will be dis- 
played at your terminal when they are typed in. The format of ECHOCONTROL 
is 

Function: ECHOCONTROL 

# Arguments: 3 


Arguments: 1) a character, CHAR 
2) a mode, MODE 
3) a terminal table address, TTBL 


Value: The previous mode for the character. 


CHAR may be either a character or a character code. MODE takes one of 
the following values: : 


Value Effect 
IGNORE The character is never printed. 
REAL The character is printed as itself. 
SIMULATE Output is simulated. 
INDICATE The character is printed, but preceded by 
an "up arrow". 
NIL The mode is not changed. 


TTBL is the address of a terminal table for which the mode control is to be 
changed. If TTBL is NIL, the current terminal table is assumed. Any mode 
change does not take effect until a terminal table is made the current terminal 
table via SETTERMTABLE. Of course, if TTBL is NIL, the effect is immediate 
because the current terminal table is assumed. 

You may force CONTROL-B to echo with an f as follows: 


*-(ECHOCONTROL 'B 'INDICATE) 
IGNORE 





: 
s 
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+ <CTRL-B)TB 
BREAK 


Echoing information may be specified for control characters only. Any other 
character will generate an error with the message ‘‘ILLEGAL ARG”. The effect 
of this function applies to all displays of the control character including the 
printing of the control character from within a program as well as echoing it on 
input. 

Note that different terminals respond to control characters in interesting 
ways. Some of the control characters may be intercepted and intepreted by the 
terminal itself, particularly with the new ‘‘smart’’ terminals. Some judicious ex- 
perimentation may be necessary to make control characters acceptable at your 
terminal. 


General Echo Control 
INTERLISP-D and INTERLISP/VAX allow you to specify echoing for any 
character, not just control characters. ECHOCHAR takes the form 


Function: ECHOCHAR 
# Arguments: 3 


Arguments: 1) a character code, CHARCODE 
2) an echo mode, MODE 
3) a terminal table address, TTBL 


Value: The old mode for the character code. 


ECHOCHAR allows you to specify echoing for any character code. CHAR- 
CODE may be a list of character codes, whence ECHOCHAR is applied to each 
character code with the same values of MODE and TTBL. 


15.6.3 Character and Line Deletion Control 


Two control characters, namely CTRL-A and CTRL-Q, control the deletion of 
characters and lines on typein. Normally, the system will backspace over the 
character (for CHARDELETE) or signify by printing ## to indicate that the re- 
spective deletions have taken place. You may modify the response to these two 
control characters to suit your application needs. In particular, you may want to 
display certain messages depending on the context in which a user attempts to 
delete characters. 

To modify deletion control for a terminal table, you must execute DELETE- 
CONTROL, which takes the form 


Function: DELETECONTROL 
# Arguments: 3 
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Arguments: 1) a type of deletion, TYPE 
. 2) a string, MESSAGE 
3) a terminal table address, TTBL 


Value: The previous message as a string. 


TYPE specifies the output protocol to be observed when a deletion control 
character is typed in. TYPE may take one of the following values: 


Value Effect 


LINEDELETE MESSAGE is printed when a LINEDELETE 
control character is typed in. The 
initial setting is "##<cr)". 


1ISTCHDEL MESSAGE is printed the first time a 
CHARDELETE control character is 
typed. The initial setting is "\". 


NTHCHDEL MESSAGE is printed on subsequent 
entries of the CHARDELETE control 
character without intervening 
characters. The initial setting is 
" ™ (e.g., the null string). 


POSTCHDEL MESSAGE is printed when a character 
other than a control character is 
entered following character or line 
deletion. The initial setting is "\". 


EMPTYCHDEL MESSAGE is printed when a CHARDELETE 
control character is typed and the 
line buffer is empty. The initial 
setting is "##{cr)". 


ECHO Any characters deleted by CHARDELETE 
are echoed at the terminal. 
NOECHO Any characters deleted by CHARDELETE 


are not echoed at the terminal. 


The combined effect of ISTCHDEL and NTHCHDEL is to display a '"'\" 
(e.g., a backslash) when the first of a sequence of characters is deleted and then 
the empty string. However, since ECHO is usually enabled for character dele- 
tion, the sequence of characters deleted will appear in reverse order on your dis- 
play. 
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+(SETQ keystone.state 'pennslyv\vyl\ylvania) 


Here I typed CTRL-As to 
delete three characters. 


Note that the deleted characters are both echoed and surrounded by '"'\"' to 
delineate them from the correct text. 

For all but, ECHO and NOECHO, the value of DELETECONTROL is the 
previous value of the message to be printed. ECHO and NOECHO return the 
previous mode. MESSAGE must be less than five characters due to timing con- 
siderations in responding to user inputs. 

The IRM suggests that you may backspace over characters rather than 
echoing them if you have a video display terminal. To do so, you may specify the 
following sequence of commands: 


(ECHOCONTROL 8 'REAL) Specifies that CTRL-H, which 
is backspace, will be 
displayed as is. 


(DELETECONTROL 'NOECHO) Eliminates echoing of 
deleted characters. 


(DELETECONTROL '1STCHDEL ''TH TH"') 

(DELETECONTROL 'NTHCHDEL "'TH TH!'') 
Obtaining the Current Deletion Control Message 
You may determine the current deletion control message by executing GETDE- 
LETECONTROL. It takes the form 

Function: GETDELETECONTROL 

# Arguments: 2 


Arguments: 1) a type of deletion, TYPE 
2) a terminal table address, TTBL 


Value: The current deletion control message for 
TYPE in TTBL. 


Consider the following examples: 


«-(GETDELETECONTROL 'LINEDELETE) 
"##< CR) 


" 


«-(GETDELETECONTROL 'NTHCHDEL) 
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+-(GETDELETECONTROL 'POSTCHDEL) 
! \t ' 


Note that when TTBL is NIL, the current terminal table is assumed. 


15.6.4 Converting to Upper Case on Typein 


INTERLISP accepts S-expressions and commands in upper-case format only 
(comments and a few other words being exceptions). Most computer systems, 
however, support both upper- and lower-case data entry. Many times, you will 
find it confusing to keep switching between lower and upper case. To remedy 
this, you may direct INTERLISP to convert all characters entered on typein to 
upper case. To do so, you must execute RAISE. It takes the form 


Function: RAISE 
# Arguments: 2 
Arguments: 1) a flag, FLAG 
2) a terminal table address, TTBL 
Value: The previous setting of FLAG. 


If FLAG is T, all characters are echoed as they are typed in, but lower-case 
characters are converted to upper case when they are passed to INTERLISP 
functions. Otherwise, all characters are passed through exactly as they are 
typed. 


Determining the Current Raise Mode 
You may determine the current raise mode for a terminal table by executing 
GETRAISE, which takes the form 





Function: GETRAISE 

# Arguments: 1 

Argument: 1) a terminal table address, TTBL 
Value: The current RAISE mode for TTBL. 


Consider the following example: 


+ (GETRAISE) 
NIL 


15.6.5 Line Length Control 


The length of the output line is usually determined by the operating system. 
Standard line length on terminals is 80 columns, but most operating systems 
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allow you to vary the line length from 1 to 132 columns. INTERLISP provides 
access to the functions that allow you to vary terminal line length. 


Setting the Terminal Line Length 
SETLINELENGTH allows you to set the terminal line length. It takes the form 
Function: SETLINELENGTH 
# Arguments: 1 
Argument: 1) a line length, N 
Value: The former setting of TTYLINELENGTH. 


If N is NIL, INTERLISP sets to the variable TTYLINELENGTH to the 
value of the terminal line length returned by the operating system. If N is not 
NIL, INTERLISP sets TTYLINELENGTH to N and calls upon the operating 
system to set the terminal line length to this value. 


< (SETLINELENGTH) 
72 


which determines the current logical record size of the terminal. 
Now, if we set the terminal line length to 10, 


«-(SETLINELENGTH 10) 
72 


< TTYLINELENGTH 
10 


«(PRINT ''The quick red fox jumped over the lazy brown dog'') 
"The quick 
red fox j 
umped over 
the lazy 
brown dog" 


Notice that INTERLISP automatically inserted (LF)<¢(CR) after the proper 
number of characters while printing the string. 

You should note that TTYLINELENGTH also affects typing in input com- 
mands, but I have not shown this feature in order to make the example above 
more readable. 


Setting the File Line Length 
A corresponding function is LINELENGTH, which allows you to set the line 
length (i.e., the logical record length) for an output file. It takes the form 
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Function: LINELENGTH 
# Arguments: 2 
Arguments: 1) a line length, N 
2) a file name, FILE 
Value: The former setting of FILELINELENGTH. 


LINELENGTH sets the logical record size of the output file FILE to N. If 


FILE is NIL, INTERLISP assumes that you meant the primary output file. The 
file must be open for output in order to determine or set the line length. 


«-(LINELENGTH NIL 'COMPLEX) 
FILE NOT OPEN 
COMPLEX 


Let us open the file first: 


«-(IOFILE 'COMPLEX) 
{KAISLER) COMPLEX. .9 
«-(LINELENGTH NIL 'COMPLEX) 
72 ‘ 


Note that if N is NIL, LINELENGTH determines the current logical record 


size of the file. 


When a file is first opened, its line length is set to the value of FILELINE- 


LENGTH. You may reset the line length at any time. You may also adjust the 
value of FILELINELENGTH for all newly opened files by resetting FILELINE- 
LENGTH via SETQ. 


Determining the Read or Write Position 
POSITION allows you to determine the character position in the current input 
or output line of a file. It takes the form 


Function: POSITION 
# Arguments: 2 


Arguments: 1) a file name, FILE 
2) a column number, N 


Value: The previous column number. 


If N is NIL, POSITION determines the column number of the next charac- 


ter to be read or printed on the specified file. Note that the file must be opened 
for input or output. If FILE is NIL, INTERLISP assumes that you mean the 
current primary input or output file. 
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< (POSITION) 
0 


A 0 is returned after an EOL has been read or printed indicating the start of 
a new line. If N is non-NIL, the column number is reset to the value of N. 


«-(IOFILE 'TEST) 
(KAISLER)TEST. .1 


«(POSITION 'TEST 20) 
0 


-(PRIN1 "BEGIN AT COLUMN 20'') 
"BEGIN AT COLUMN 20" 


<(CLOSEF 'TEST) 
«KAISLER)TEST. .1 
And TEST would have the appearance on disk 
222222222233333333334 
1234567890123456789012345678901234567890 
BEGIN AT COLUMN 20 


15.7 PRETTYPRINTING 


The syntax of S-expressions often becomes an obtuse jumble of symbols and 
parentheses. If you are not careful, running together pieces of different expres- 
sions makes your code unreadable. Prettyprinting is the process of displaying S- 
expressions in a structured format that makes them both readable and under- 


standable. 
INTERLISP includes three functions for handling prettyprinting chores. 


15.7.1 Generalized Prettyprinting 
PRETTYPRINT is the standard system prettyprinting function. It takes the 
form 

Function: PRETTYPRINT 


# Arguments: 2 


Arguments: 1) a list of functions, FNS 
2) a pretty definition flag, PRETTYDEF 


Value: The value of FNS. 


PRETTYPRINT always directs its output to the current primary output file 
(which was set by OUTPUT if not the default). Consider the following example: 
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«-(PRETTYPRINT '(depth) ) 
(depth 
(LAMBDA (1st) 
(COND 
((NULL 1st). 0) 
((ATOM (CAR 1st)) 
(depth (CDR l1st))) 
((GREATERP (ADD1 (depth (CAR 1st) )) 
(depth (CDR 1st))) 
: (ADD1(depth (CAR 1st)))) 
T 
(depth (CDR 1st))))) 


You will note that we have prettyprinted the functions and examples de- 
scribed in this text because it makes them both readable and understandable as 
well as pleasing to the eye. 

PRETTYPRINT works on functions that have been broken or advised. It 
also works on functions which have been compiled but whose source has been 
saved on their property list. 

If PRETTYPRINT is given an atom which is not the name of a function, but 
which has a value, it will treat the value of the atom as a sequence of function 
names. 


«-(SETQ x '(EQUAL (CAR y) (CDR z))) 
(EQUAL (CAR y) (CDR 2z)) 


<(PRETTYPRINT x) 
(EQUAL not printable) 
((CAR y) not printable) 
((CDR z) not printable) 
(EQUAL (CAR y) (CDR 2z)) 


Functions, whose names are given to PRETTYPRINT, may not have their 
definitions loaded into memory. However, if the function resides in a file that is 
currently noticed by the File Package, INTERLISP will load the function defini- 
tion using LOADFNS (see Section 17.9.2). It will then print the definition as 
described above. 

As a last resort, PRETTYPRINT attempts spelling correction on an argu- 
ment. If this fails, PRETTYPRINT returns the error message ({atom) NOT 
PRINTABLE). 

PRETTYDEFFLG has the value T when PRETTYPRINT is called from 
PRETTYDEF (see Section 17.8.1). This flag causes PRETTYPRINT to print 
the name of the current function it is writing to the output file as an indication of 
its progress. 
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A Definition for PRETTYPRINT 
We might define PRETTYPRINT as follows: 


(DEFINEQ 
(prettyprint (lst prettydefflg) 
(PROG (expression fn definition) 
(COND 
((ATOM 1st) 
(* 
If given an atom, listify 
it so that PRETTYPRINT may 
attempt to work correctly. 


(SETQ lst (LIST lst)))) 
loop 
(COND 
((NULL lst) 
(RETURN NIL) ) 
((AND prettydeffflg 
(NEQ (OUTPUT) T) 
(* 
If the current output file 
is not the terminal, print 
the first function name on 
the terminal to let the 
user know what progress we 
are making in printing the 
list of functions. 
) 
(PRINT (CAR lst) T))) 
(SETQ fn (CAR lst)) 
loop1 
(* 
Get the definition of the function 
for printing. 


) 
(SETQ definition 


(COND 
((CDR fn) 
(VIRGINFN fn) ) 
(GETD fn)))) 
(COND 


((AND (NULL definition) 
(SETQ expression 
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(FNCHECK fn 


* 
prettydefflg) )) 
(RPLACA lst (SETQ fn 
expression) ) 
(GO loop1) ) 
((NULL (EXPRP definition) ) 
(* 


If the function does’ not 
have an definition or an 
EXPR property, then it is 
not printable. 


) 
(PRIN1 fn) 
(SPACES 1) 
(PRIN1 "not printable'') 
(TERPRI) 
(RETURN NIL) ) 
(T 


FN is not the name of a 
function, but it may be 
misspelled, so attempt 
spelling correction if DWIM 
is enabled. 


(AND DWIMFLG 
(SETQ fn (ADDSPELL fn))) 
(x 


CLISPIFY the definition as 
well. 


) 
(SETQ definition 
(CLISPIFY definition) ) ) 

(TERPRI) 
(PRIN1 '%()) 
(PRINT fn) 
(PRINTDEF definition) 
(PRIN1 '%))) 
(TERPRI) ) ) 

(SETQ lst (CDR lst)) 

(GO loop) ) 

)) 
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15.7.2 Prettyprinting to the Terminal 


PP prettyprints the value of its argument to the terminal. It takes the form 


Function: PP 
# Arguments: 1-N 
Arguments: 1) a function name, FN 
2-N) function names, FN[2] 
. FN(N] 
Value: A list of the function names. 


PP is an NLAMBDA, nospread function. Consider the following example: 


«(PP 'REAL 'IMAG) 
(REAL 
(LAMBDA (CX) **COMMENT** 
(RECORDACCESS (QUOTE REAL) 
CX NIL (QUOTE FETCH) ))) 


(IMAG 
(LAMBDA (CX) **COMMENT** 
(RECORDACCESS (QUOTE IMAG) } 
CX NIL (QUOTE FETCH) ))) 


(REAL IMAG) 
In effect, PP could be defined as follows: 


(DEFINEQ 
. (pp (fn) 
(OUTPUT T) 
(SETREADTABLE T) 
(LINELENGTH TTYLINELENGTH) 
(PRETTYPRINT fn) 
)) 


A much better definition of PP appears as follows: 


(DEFINEQ 
(pp 
(NLAMBDA fnslst 
(PROG ((y (OUTPUT T))) 
(OR 
(ERSETQ 
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(PRETTYPRINT 

(COND 

((ATOM fnslst) 
(LIST fnslst) ) 

(T fnsist)))) 

(TERPRI T) ) 

(OUTPUT y) 
(RETURN fnsist)) 
))) 


Note that this definition saves and restores the primary output file while 
printing the specified function to the terminal. 
PP treats unknown functions in a fashion similar to PRETTYPRINT. 


15.7.3 Displaying Prettyprinted Definitions from a File 


PF allows us to display a prettyprinted definition from a file without actually 
loading the definition into memory. Note that both PRETTYPRINT and PP will 
load a function prior to displaying it if the function is noticed on a file. PF merely 
copies the bytes from a file to another file (typically the terminal without con- 
suming space to store the function definition. It takes the following format: 


Function: PF 
# Arguments: 3 


Arguments: 1) a function name, FN 
2) a list of file name, FROMFILES 
3) a file name, TOFILE 


Value: NIL 


PF is an NLAMBDA, nospread function. PF copies the definition of FN 
from each file named in FROMFILES to TOFILE. There are two cases: 


1. If TOFILE is NIL, PF displays the definition(s) on the terminal. 


2. If FROMFILES is NIL, PF invokes WHEREIS (see Section 17.3.8) to 
locate the file definition (if it resides in any of the noticed files). 


Consider the following example: 


«(PF COMPLEX COMPLEX T) 
[from <«KAISLER)COMPLEX. .9] 
(COMPLEX 

(LAMBDA (R I) **COMMENT** 


NIL 
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When PF prints to a terminal, it transforms the characters read from the 
file. Transformations occur because source definitions may be written to files in 
a variety of formats. PF does the following: 


1. Removes font information. 


2. Does not print the change character that marks revisions to the function 
definition. 

3. Reduces the left margin to accommodate long expressions that may have 
been written to the file (e.g., those exceeding TTYLINELENGTH). 

4. Suppresses comments, if **COMMENT**FLG is non-NIL. 


15.7.4 Prettyprinting Symbolic Files 
A generalized prettyprinting function is PRINTDEF, which takes the form 


Function: PRINTDEF 
# Arguments: 6 


Arguments: 1) an S-expression, EXPRESSION 
2) a left-hand margin, LEFT 
3) a definition flag, DEFFLAG 
4) a tail flag, TAILFLAG 
5) a list of functions, FNSLST 
6) a file name, FILE 


Value: The value of EXPRESSION. 


PRINTDEF is described in more detail in Section 17.8 because it is used to 
place symbolic information in files. 


15.7.5 Prettyprinting Control Variables 


You may set the values of several variables to control the appearance of the pret- 
typrinted output: 


#RPARS Determines how many right 
parentheses are necessary for 
substitution by square brackets. 
#RPARS is initialized to 4. If 
#RPARS is set to NIL, no square 
brackets will be substituted for 
right parentheses. 


Consider the following example: 


«-(SETQ #RPARS NIL) 
NIL 
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(PP 'power) 


((ZEROP Y) 1) 


(power 
(LAMBDA (x y) 
(COND 
(T 
)) 
(POWER) 


But, if we reset #RPARS 


+(SETQ #RPARS 3) 
3 


(PP 'power) 


(power 
(LAMBDA (x y) 


(TIMES x 


(power x (SUB1 y))))) 


(power x (SUB1 y) 


(POWER) 
#CAREFULCOLUMNS 


CHANGECHAR 


PRETTYPRINT approximates the 
number of characters in each 
atom rather than actually 
counting them. This approach 
work well in most cases, but 
unusually long atom names will 
cause your output to assume a 
rather ragged appearance because 
PRETTYPRINT wraps around to the 
next line. Setting 
#CAREFULCOLUMNS to a non-zero, 
non-negative number causes 
PRETTYPRINT to compute the 
number of characters from the 
right hand margin. A value of 20 
is probably sufficient. 
#CAREFULCOLUMNS is initialized 
to 0. 


When PRETTYPRINT prints to the 
terminal, you may annotate the 
listing to show changes made to 


CLISPIFYPRETTYFLG 
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the S-expressions. PRETTYPRINT 
displays the value of 
CHANGECHAR, if non-NIL, in the 
right-hand margin for all S- 
expressions that the editor has 
marked as changed. CHANGECHAR 
initially has the value |. 


If this variable is non-NIL, 
PRETTYPRINT invokes CLISPIFY to 
transform the S-expression 
before printing them (see 
Chapter 23). 


<(SETQ CLISPIFYPRETTYFLG T) 


«(PP POWER) 
(power 


(LAMBDA (x y) 


(4f Y=0 
then 1 


else (TIMES X (POWER x Y-1) 


(POWER) 
COMMENTFLG 


FIRSTCOL 


PRETTYPRINTMACROS 


PRETTYPRINT compares the CAR of 
each S-expression to this 
variable. If they are EQ, the S- 
expression is treated as a 
comment (see Section 16.10). 
COMMENTFLG initially has the 
value *. 


Specifies the starting column 
for printing comments. Its 
initial value is 48. (See 
Section 16.10 for a discussion 
of how comments are printed.) 


Its value is an association list 
that allows you to format 
selected S-expressions. 
PRETTYPRINT compares the CAR of 
each S-expression to be printed 
with the CAR of the entries on 
the association list. If a match 
is found, the CDR of the 
association list entry is 
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PRETTYPRINTYPEMACROS 


applied to the S-expression. If 
the result is NIL, PRETTYPRINT 
ignores the S-expression; 
otherwise, it prints it in the 
normal fashion. Thus, you may 
substitute one S-expression for 
another during printing. Its 
value is initially NIL. 


Its value is a list of elements 
having the form 


(<typename) . <function)) 


For each datatype other than 
lists and atoms, the type name 
is looked up on 
PRETTYPRINTYPEMACROS. If found, 
the function is applied to the 
expression. This allows you to 
format different datatypes such 
as arrays. Its value is 
initially NIL. 


For example, to print an array using PP, we could define PRETTYPRIN- 


TYPEMACROS as follows: 


«-(SETQ PRETTYPRINTYPEMACROS '(ARRAYP . PRINT. ARRAYP) ) 


(ARRAYP . PRINT.ARRAY) 
PRETTYEQUIVLST 


PRETTYFLG 


Its value is an association list 
to treat certain S-expressions 
like other S-expressions. For 
example, many File Package 
functions define forms using’ 
NLAMA. You can tell PRETTYPRINT 
to treat these expressions like 
NLAMBDAs. using the following 
form: 


(NLAMA . NLAMBDA) 


If PRETTYFLG is NIL, PRINTDEF 
will use PRIN2 to print an 
expression instead of 
prettyprinting it. It is 
initially set to T. 


PRETTYTABFLG 
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File space is often of 
Significant concern to many 
users. The prettyprinting 
functions normally put spaces in 
the file to properly align the 
output, but at the cost of 
substantial quantities of space. 
You may save this space by 
replacing the spaces with tabs 
(assuming one tab is equivalent 
to 8 spaces). Tabs are not used 
if PRETTYTABFLG is NIL; it is 
initially set to T. 


15.8 THE PRINTOUT PACKAGE 
INTERLISP provides a set of standard printing functions including 


PRIN1, PRIN2, PRINT 


TAB 


SPACES 


PRINTNUM 


PRINTDEF 


print an object on the specified 
output file 


position the cursor at a 
specified location in the 
current print line 


insert 1 or more spaces at the 
current print position 


print numbers in appropriate 
format 


prettyprint expressions 


By executing various combinations of these functions, you may format your 
output in any number of ways. To simplify the creation of certain formats, IN- 
TERLISP provides the Printout Package which implements a formatting lan- 
guage that specifies complicated sequences of the basic printing functions. 

The Printout Package is implemented through CLISP (see Chapter 23). 
PRINTOUT is a CLISP word which is translated by DWIMIFY to the appropri- 
ate set of functions that achieve the desired effect. PRINTOUT takes a descrip- 
tion of the desired format and prints it on the specified output file. A PRINT- 


OUT description has the form: 


(PRINTOUT <file) 
«printcom1) 
{printcom2) 


(printcomN)) 
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The <file> parameter specifies the file to which the output will be sent. The 
terminal must be explicitly specified as T in this form. The (printcom) parame- 
ters are forms that describe the individual printing events. A ( printcom) may be 
a Printout Package command or an S-expression that is evaluated and whose 
value is to be printed. 

If <file>) is not the primary output file, the primary output file is ‘‘remem- 
bered”’ and <file> becomes the primary output for the duration of the PRINT- 
OUT expression execution. 

PRINTOUT commands may be divided into several logical categories. Fol- 
lowing the IRM, these commands are discussed in the following sections. 


15.8.1 Horizontal Spacing Commands 


A horizontal spacing command provides a mechanism for moving the cursor to a 
new position within the current print line. In general, these commands will be 
translated to expressions that use TAB or SPACES. The horizontal spacing 
commands are 


{n) {n> is a positive integer. The cursor 
is moved to the absolute position <n) 
within the current print line. If the 
print line cursor lies beyond <n), 
the file will be positioned at <n) on 
the next line (e.g., following an 
implicit TERPRI). 


“—n) A negative integer indicates relative 
spacing forward in the print line. 
The print line cursor is moved 
forward <n) positions. 


-TAB <position) This command is equivalent to <n), 
but makes the PRINTOUT expression 
easier to read and understand. 
<position) is an expression that is 
evaluated to produce an integer that 
is the absolution position. The print 
line cursor is moved to the specified 
position. If the print line cursor 
lies beyond the value of <position), 
the file will be placed at the value 
of <position) on the next line. 


-TABO <position) Similar to .TAB but the value of 
<position) may be zero whence the 
print line cursor is not moved. 
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One, two, or three apostrophes are a 
shorthand mechanism for specifying 
that one, two, or three spaces should 
be inserted in the current print 
line. They are equivalent to -1, -2, 
-3 respectively. 


.SP <distance) Moves the print line cursor a total 
of <distance) spaces where (distance) 
is an S-expression to be evaluated. 
If <distance) is an integer, then .SP 
n and «-n) are equivalent. 


- RESET Resets the current line by moving the 
print line cursor to the beginning of 
the line (via a carriage return 
without a line feed). You may use 
-RESET to position the cursor for 
overprinting of a line. 


15.8.2 Vertical Spacing Commands 


A vertical spacing command inserts a number of carriage returns or form-feeds 
in the output file. If you are printing to T, the effect is to see your output move up 
the screen. The vertical spacing commands are: 


i Inserts a carriage return and line 
feed into the file. It is equivalent 
to executing (TERPRI). The same 
effect may be achieved by inserting a 
0 as a PRINTOUT command as this 
forces the file to move to position 0 
(i.e., column 1) of the next line. 


-SKIP <lines) Inserts a number of carriage returns 
into the output file. <lines) is an 
S-expression that is evaluated to 
produce the distance to be skipped. 


. PAGE Inserts a form-feed into the output 
file that causes a page to be ejected 
to the top of form when it is 
encountered. 


15.8.3 Printing Specifications 


PRINTOUT will use PRIN1 to print the values of expressions that are contained 
in a PRINTOUT form. PRIN1 may not be appropriate for every expression. 
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Additional printing commands are provided to allow you to choose alternative 
modes of output. The printing specifications are 


-P2 <expression) The value of <expression) is 
printed using PRIN2. 
-PPV <expression) The value of" expression) is 


prettyprinted beginning at the 
current print line position 
using PRINTDEF. PPV treats 
<expression) as a variable 
rather than a function. 


.PPF <expression) The value of <expression) is 
prettyprinted as part of a 
function definition. Various 
INTERLISP functions that 
identify significant expressions 
in a function (such as PROG, 
SELECTQ, CLISP words) receive 
special formatting treatment. 


-PPVITL <expression) The value of <expression) is 
printed as a tail, i.e., without 
the surrounding parentheses if 
it is a list. It is often used 
for prettyprinting sublists of a 
list whose other elements are 
formatted with other commands. 


-PPFTL ¢(expression) The value of <expression) is 
prettyprinted as a tail, but is 
treated as part of a function 
definition. 


15.8.4 Structure Specifications 


The prettyprinting routines will display the structure of S-expressions but are 
not designed to handle formatted text. Text is generally printed as a series of 
paragraphs whose left and right margins are defined to alter its shape. If you 
think of the page as a window in which you place blocks of text, then much of the 
time you will try to place your text so that is both appealing and pleasant to the 
reader as well as functional in purpose. The following commands are concerned 
with the shape and placement of a block of text. 


Paragraph Specifications 
You may specify a paragraph using the .PARA command. It takes the form 
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.PARA <lmargin) <rmargin) <list) 


where (list) is printed as a paragraph within the boundaries specified by 
<Imargin) and <rmargin), respectively. In general, (list) is a list of individual 
atoms arrayed as a stream to be printed. .PARA uses PRIN to print the list. An 
alternate form, .PARA2, uses PRIN2 instead. 


Right Margin Flushing 

In general, the PRINTOUT package will print paragraph lines with a right jag- 
ged edge. Many technical publications require contents of a paragraph to be 
flush against the right margin. Usually, text processors accomplish this by hy- 
phenating words or introducing spaces between words to ensure that the line 
appears to be properly proportioned. The Printout Package allows you to per- 
form right-flushing using the .FR command. It takes the form 


-FR <position) <expression) 


where (position) determines the position where the right end of <expression) 
will line. < position) is interpreted as follows: 


1. 0 indicates the right margin 
2. )0 indicates the absolute position in the line 
3. <0 indicates a number of positions to the right of the current position 


An alternative form, .FR2, uses PRIN2 rather than PRIN] to print the value 
of the expression. 


Centering an Expression 

Titles and other significant expressions are usually centered in a line to draw 
attention to their content. You may center an expression using the .CENTER 
command. It takes the form 


.CENTER <position) (expression) 


which centers the value of (expression) between the current position and ¢ posi- 
tion). <position) is interpreted as described in 15.8.4.2. 

An alternative form, .CENTER2, uses PRIN2 to print the value of (expres- 
sion). 


Printing Numbers 

When you print numbers using the INTERLISP printing functions, they do their 
own internal formatting of the string representing the number. We described the 
Printnum Package in Section 15.4; it allows you to specify different formats for 
printing both integer and floating point numbers. The Printout Package allows 
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you to use some of the features of the Printnum Package via the following com- 


mands: 


.-1<format) (number) 


.F{ format) <number) 


Print (number) as an integer 
using PRINTNUM with a FIX format 
list constructed from <format). 


Print (number) as a floating 
point number using PRINTNUM with 
a FLOAT format list constructed 
from <format). 


Note that the format specification immediately follows the command name. 


-15.-8.T 


is translated to the format list (FIX 5 -8 T). 
Individual elements of the format specification are separated from each 


other by periods. 


.N <format) (number) 


Both .I and .F translate to 
PRINTNUM calls with quoted 
format specifications. .N allows 
you to call PRINTNUM with an 
expression which is evaluated to 
produce a format specification. 


Note that the expression which produces the format is a separate list element 
rather than immediately following the ._N command. 


16 





File Management and 
Operations 


Most programs require external storage for data. To accomplish this, IN- 
TERLISP provides a set of functions for declaring external files to the system 
and performing operations upon them. This chapter discusses the basic file 
management functions and operations. 

Most of the input/output functions described in the previous chapters may 
specify an optional file name as an argument. Most of these function require that 
the file already be open before it can be operated upon. INTERLISP maintains 
an internal data structure which describes open files and their status. Some im- 
plementations of INTERLISP utilize the capabilities of the underlying operating 
system to provide file management services. Thus, certain features of the file 
management software may not be available in every implementation. 


16.1 FILE STRUCTURES AND NAMES 


INTERLISP uses the file management functions of the host operating system 
whenever possible. In INTERLISP/370, the file management functions of the 
VM/SP operating system are used. Similarly, INTERLISP-10 and IN- 
TERLISP/VAX use the features of TENEX and UNIX, respectively. In IN- 
TERLISP-D, which provides its own operating system, many of these functions 
are encoded into the virtual machine that supports INTERLISP-D. 


16.1.1 The VM/SP File System 


The VM/SP file system is a flat file system. Files reside on minidisks which are 
logical entities that are subsets of a physical disk drive. VM/SP manages one or 
more minidisks for each user. Minidisks are identified by letters. The primary 
minidisk associated with a user identifier is labeled A. Subsequent disks are la- 
beled B, C, D, and so on. Depending on the configuration data, a user may have 
from 1 to 26 minidisks accessible at any time, although he may have more mini- 
disks associated with his virtual machine. 
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File names in the VM/SP operating system consist of up to eight characters, 
of which the first cannot be a number but all others may be; an eight-character 
file type such as FORTRAN, MODULE, etc.; and a minidisk identifier. Sub- 
directories and rooted tree structures common in other operating systems are not 
possible under VM/SP. You should consult the appropriate IBM manuals for 
further details about the VM/SP operating system. 


16.1.2 The INTERLISP-D and INTERLISP-10 File Systems 


INTERLISP-D supports a flexible file system where files may reside on the disk 
local to the Xerox 11xx Scientific Information Processor or on a file server acces- 
sible through the Ethernet. 

Each file has a name that may consist of up to 40 alphanumeric characters 
including the punctuation marks +—$. Blanks are not allowed in a file name. 
Upper- and lower-case characters may be intermixed in a file name. However, 
they are not distinguished. INTERLISP-D translates all file name characters to 
upper case internally in order to operate upon them. When INTERLISP-D cre- 
ates a file name, it will do so in upper-case letters. 

Users of the TENEX version of INTERLISP will recognize that the file 
names have the same form except for a device/host name prefix. In IN- 
TERLISP-10, the file name may be prefixed by a directory name which is en- 
closed in angle brackets. Thus, a file name has the following format: 


INTERLISP-D: 

{device/host name}file name.file type;version 
INTERLISP-10: 

{directory-name)file name.file type;version 


Files that reside on a Xerox 11xx processor’s local disk belong to the device/ 
host [DSK]. Files residing on other hosts will have the name of that host prefixed 
to the file name. For example, if files resided on a host whose name is RE- 
SEARCH, then to access those files you would prefix the host name [RE- 
SEARCH] to the file name. 

File types are used to distinguish instances of a file name according to its 
contents, e.g., if you are working on a major INTERLISP project, you will prob- 
ably keep several files containing various sorts of information. This information 
includes a SYSOUT which is the executable file, a LISPIN containing your pro- 
gram’s source code, and perhaps a DATA file. By appending the file type (either 
SYSYOUT, LISPIN, or DATA) to the file name, you can distinguish the con- 
tents of the file and yet maintain uniformity in your file naming conventions. 

The version of a file merely marks the current instance of the file. Any num- 
ber of versions may reside on the disk or the file server. The INTERLISP func- 
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tions and predicates that manipulate files always retrieve the latest version of the 
file unless a version is explicitly specified in the argument to one of these func- 
tions. It is good practice to always keep at least one or two old versions of a file on 
the disk. More than that tends to clutter the disk and consume space that may 
otherwise be needed for data. 

Unlike INTERLISP-10, [DSK] and the file servers do not support tempo- 
rary files. Files that are created remain in place until you specifically delete 
them. However, you can simulate temporary files by defining them to reside in 
your virtual memory. To do so, prefix the file name with the host name [CORE]. 
All files defined in this manner reside within the user’s virtual memory; they are 
saved with a SYSOUT of your virtual memory and are only lost when your virtual 
memory is abandoned. 


16.2 FILE DECLARATION 


Before a program can use a file, it must declare it to the system. A file may be 
declared to be input, output, or both upon its opening. After a file has been 
opened, the program may specify a file to be either its primary input or output 
file. When this occurs, all input will be accepted from or output directed to that 
file until a new declaration is executed. 


16.2.1 The Primary File ‘T’ 


When an INTERLISP program is initiated, it has associated with it a primary 
file for input and output operations. This file is commonly known as the file “T’ 
and is associated with the user’s terminal. Until this primary file is changed, all 
input is accepted from and all output is directed to the user’s terminal unless an 
optional file name is specified in the I/O function. For example, executing the 
PRINT function produces the indicated string on the user’s terminal: 


«(PRINT "Welcome to INTERLISP") 
"Welcome to INTERLISP" 


T is always considered to be open. 


16.2.2 Declaring the Primary Input File 


You may declare new primary files for input or output using two functions pro- 
vided by INTERLISP. 
To declare a new primary input file, you use INPUT, which takes the form 


Function: INPUT 
INFILE 


# Arguments: 1 
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File names in the VM/SP operating system consist of up to eight characters, 
of which the first cannot be a number but all others may be; an eight-character 
file type such as FORTRAN, MODULE, etc.; and a minidisk identifier. Sub- 
directories and rooted tree structures common in other operating systems are not 
possible under VM/SP. You should consult the appropriate IBM manuals for 
further details about the VM/SP operating system. 


16.1.2 The INTERLISP-D and INTERLISP-10 File Systems 


INTERLISP-D supports a flexible file system where files may reside on the disk 
local to the Xerox 11xx Scientific Information Processor or on a file server acces- 
sible through the Ethernet. 

Each file has a name that may consist of up to 40 alphanumeric characters 
including the punctuation marks +—$. Blanks are not allowed in a file name. 
Upper- and lower-case characters may be intermixed in a file name. However, 
they are not distinguished. INTERLISP-D translates all file name characters to 
upper case internally in order to operate upon them. When INTERLISP-D cre- 
ates a file name, it will do so in upper-case letters. 

Users of the TENEX version of INTERLISP will recognize that the file 
names have the same form except for a device/host name prefix. In IN- 
TERLISP-10, the file name may be prefixed by a directory name which is en- 
closed in angle brackets. Thus, a file name has the following format: 


INTERLISP-D: 

{device/host name}file name.file type;version 
INTERLISP-10: 

{directory-name)file name.file type;version 


Files that reside on a Xerox 11xx processor’s local disk belong to the device/ 
host [DSK]. Files residing on other hosts will have the name of that host prefixed 
to the file name. For example, if files resided on a host whose name is RE- 
SEARCH, then to access those files you would prefix the host name [RE- 
SEARCH] to the file name. 

File types are used to distinguish instances of a file name according to its 
contents, e.g., if you are working on a major INTERLISP project, you will prob- 
ably keep several files containing various sorts of information. This information 
includes a SYSOUT which is the executable file, a LISPIN containing your pro- 
gram’s source code, and perhaps a DATA file. By appending the file type (either 
SYSYOUT, LISPIN, or DATA) to the file name, you can distinguish the con- 
tents of the file and yet maintain uniformity in your file naming conventions. 

The version of a file merely marks the current instance of the file. Any num- 
ber of versions may reside on the disk or the file server. The INTERLISP func- 
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tions and predicates that manipulate files always retrieve the latest version of the 
file unless a version is explicitly specified in the argument to one of these func- 
tions. It is good practice to always keep at least one or two old versions of a file on 
the disk. More than that tends to clutter the disk and consume space that may 
otherwise be needed for data. 

Unlike INTERLISP-10, [DSK] and the file servers do not support tempo- 
rary files. Files that are created remain in place until you specifically delete 
them. However, you can simulate temporary files by defining them to reside in 
your virtual memory. To do so, prefix the file name with the host name [CORE]. 
All files defined in this manner reside within the user’s virtual memory; they are 
saved with a SYSOUT of your virtual memory and are only lost when your virtual 
memory is abandoned. 


16.2 FILE DECLARATION 


Before a program can use a file, it must declare it to the system. A file may be 
declared to be input, output, or both upon its opening. After a file has been 
opened, the program may specify a file to be either its primary input or output 
file. When this occurs, all input will be accepted from or output directed to that 
file until a new declaration is executed. 


16.2.1 The Primary File ‘T’ 


When an INTERLISP program is initiated, it has associated with it a primary 
file for input and output operations. This file is commonly known as the file “T” 
and is associated with the user’s terminal. Until this primary file is changed, all 
input is accepted from and all output is directed to the user’s terminal unless an 
optional file name is specified in the I/O function. For example, executing the 
PRINT function produces the indicated string on the user’s terminal: 


«(PRINT "Welcome to INTERLISP") 
"Welcome to INTERLISP" 


T is always considered to be open. 


16.2.2 Declaring the Primary Input File 


You may declare new primary files for input or output using two functions pro- 


vided by INTERLISP. 
To declare a new primary input file, you use INPUT, which takes the form 


Function: INPUT 
INFILE 


# Arguments: 1 
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Arguments: 1) a file name, FILE 
Value: The current primary input file. 


For example, to declare the card reader to be the primary input file, we can 
use the following expression (in INTERLISP/370): 


«(INPUT 'rdr) 
T 


INPUT returns as its value the name of the old primary input file. It is gen- 
erally a good idea to retain the name of the old primary input file (via SETQ) if 
you switch among several input files. 

Note that (INPUT) returns the name of the current primary input file with- 
out changing its name. 


< (INPUT) 
<KAISLER)MY=INPUT.DAT;4 


Executing (INPUT T) makes the primary input file the user terminal. 
The file that you declare as the primary input file must already be open for 
input: 


«(INPUT 'TEST.DAT) 
FILE NOT OPEN 
TEST.DAT 


If the file is not open, an error message is printed and the primary input file 
is not changed. 

You may specify a string as an input “file” without needing to open it. Con- 
sider the following example: 


<(INFILE "JUNK") 
T 


< (INPUT) 
"JUNK" 


< (READ) 
END OF FILE 
NIL 


(INPUT) 


because the input operation has removed characters from the string. Reading 
against the string will cease if it encounters the characters STOP in the string. 
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<(INFILE "JUNK STOP") 
"JUNK STOP" 


+ (READFILE) 
( JUNK) 


I do not recommend that you use the feature of the INFILE/READ func- 
tions to obtain data. 


Opening a File as the Primary Input File . 
An alternative function, INFILE, opens the file for input and makes it the pri- 
mary input file. 


«-(INFILE 'COMPLEX) 
i 


(INPUT) 
«KAISLER) COMPLEX. .9 


In INTERLISP-D, if the file will not open, INFILE generates an error mes- 
sage: 


<-(INFILE <some file name)) 
File Won't Open 


and the primary input file is not changed. 


A Definition for INFILE 
We might define INFILE as follows: 


(DEFINEQ 
(infile (file) 
(PROG (name) 
(COND 
((SETQ name (INFILEP file)) 
(OPENFILE name 'INPUT 'OLD) 
(RETURN (INPUT name) ) ) 


(ERROR "FILE NOT FOUND" file)))) 
)) 


16.2.3 Declaring the Primary Output File 


The corresponding function for redeclaring the primary output file is OUTPUT, 
which takes the form 
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Function: OUTPUT 
OUTFILE 
# Arguments: 1 
Arguments: 1) a file name, FILE 
Value: The current primary output file. 


OUTPUT and OUTFILE operate in the same manner as INPUT and IN- 
FILE: 


“(OUTPUT 'SCORES.DAT) 
FILE NOT OPEN 
SCORES . DAT 


<(OUTFILE 'SCORES.DAT) 
T 


< (OUTPUT) 
{KAISLER)SCORES.DAT;1 


Note that if the file does not previously exist, INTERLISP creates the file 
name in its internal file list with the version number of 1. The file is also created 
on disk. If the file already exists, a new file with the next higher version number 
is created and opened for output. 

A string may not be used to specify the file name for either OUTPUT or 
OUTFILE: 


<(OUTFILE '"JUNK") 
ARG NOT LITATOM 
"JUNK" 


A Definition for OUTFILE 
We might define OUTFILE as follows: 


(DEFINEQ 
(outfile (file) 
(PROG (name) 
(COND 
((NOT (LITATOM file)) 
(ERROR "ARG NOT LITATOM" file) )) 
(COND 
((SETQ name (OUTFILEP file) ) 
(OPENFILE name 'OUTPUT 'NEW) 
(RETURN (OUTPUT name) )) 
(T : 
(ERROR "FILE NOT FOUND" file) ))) 
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16.2.4 Testing Input/Output Files 


Generally, you do not want to attempt to open a file if such an action will result 
in an error because the file does not exist. INTERLISP provides predicates for 
testing whether a file may be opened for input or output. They take the form 


Function: INFILEP 
OUTFILEP 
# Arguments: 1 
Arguments: 1) a file name, FILE 
Value: The full name of the file; otherwise, NIL. 


INFILEP and OUTFILEP return the full name of the file that is the argu- 
ment to the predicate if the file could be opened for input or output, respectively. 
For example, assume that our program required a data file named PRESI- 
DENTS.LISPIN that contained some INTERLISP S-expressions concerning 
presidents. Before opening this file for input, we would like to ensure that the file 
actually exists. By using the INFILEP predicate, we can test whether or not IN- 
TERLISP recognizes the file: 


<-(INFILEP 'presidents.lispin) 
[DSK]presidents.lispin;1 


Note that both INFILEP and OUTFILEP return the full name of the file if it 
is recognized by the system. In this case, the full name form corresponds to that 
recognized by INTERLISP-D as the name of the file residing on the disk or file 
server. 

In INTERLISP-10, if no version number is specified, INTERLISP seeks out 
the highest version number of the file and returns its full name for INFILEP and 
one version greater than the highest existing version for OUTFILEP. 


16.2.5 File Name Recognition 


INTERLISP provides a generic function for recognizing a file, FULLNAME, 
which takes the following form: 


Function: FULLNAME 
# Arguments: 2 
Arguments: 1) a file name, NAME 
2) a recognition mode, RECOG 
Value: The full name of the file. 


FULLNAME attempts to locate a file on local disk or file server (IN- 
TERLISP-D) or in a system directory (INTERLISP-10) with the specified file 
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name. If the file is found, its full name is returned as the result of the function 
call. 

There are four possible recognition modes accepted by FULLNAME: OLD, 
NEW, OLDEST, and OLD/NEW. OLD/NEW is interpreted to mean that if 
recognition fails because no old version of the file exists, then recognize the file 
as NEW. This mode is useful only when attempting to recognize a file for writ- 
ing. 

Consider the following examples, given that there are several versions of the 
file PRESIDENTS.LISPIN (numbered 1 to 3) residing on [DSK]. 


<-(FULLNAME 'presidents.lispin OLD) 
[DSK]presidents.lispin; 3 


returns the most recent of the old versions of the file. 


«<-(FULLNAME 'presidents.lispin NEW) 
[DSK]presidents.lispin;4 


returns the next version of the file. 


<(FULLNAME 'presidents.lispin OLDEST) 
[DSK]presidents.lispin;1 


returns the oldest existing version of the file. 


«-(FULLNAME 'presidents.lispin OLD/NEW) 
[DSK]presidents.lispin;3 


Note that specifying NEW as the recognition mode always returns a version 
that is one greater than the current oldest version of the file. This mode succeeds 
even if the file does not exist. 

Note that the recognition modes do not have to be quoted as FULLNAME 
does not evaluate them. Any other mode specification results in the error mes- 
sage ILLEGAL ARG. The first argument must have a literal atom as its value; 
otherwise, the error message ARG NOT LITATOM is returned. 


16.3 OPENING A FILE 


Using INFILE and OUTFILE, we have seen that we can open a file for input or 
output, respectively, with a number of default attributes set by the system. IN- 
TERLISP provides two general functions for opening a file, OPENFILE and 
IOFILE, that allow you to establish the attributes of the file, and a predicate for 
testing if a file is open, OPENP. 
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16.3.1 A General File Open Function 


‘ OPENFILE takes a varying number of arguments depending on the attributes 
that you wish to set. Let us define the generic format for the function and then 
discuss each argument in detail: 


Function: OPENFILE 

# Arguments: 2-5 

Arguments: 1) an S-expression specifying a file name, 
NAME 


2) an access mode, ACCESS 

3) a recognition mode, RECOGNITION 

4) the byte size for the file, SIZE 

5) a list of machine-dependent parameters, 
PARMS 


Value: The full name of the file if it recognized 
and opened; otherwise NIL. 


At a minimum, you must specify a file name and an access mode to OPEN- 
FILE; other arguments are optional whence the system will assume defaults. 

Access mode may take one of four values: INPUT, OUTPUT, BOTH, or 
APPEND. These define the operations a user may perform upon the file. If the 
file is opened in APPEND mode, the system automatically positions the file 
pointer at the end of the file. 

INPUT access mode limits operations upon the file to reading from the file. 
Attempts to write to the file will cause an error. OUTPUT or APPEND access 
mode limits operations upon the file to writing to it (including moving the file 
pointer). Note that OUTPUT access mode always implies that you want to create 
a new version of the file even if you specified a version number in the file name. 
BOTH allows you to both read and write to the file. If you want to read and write 
to a file, and preserve the contents of the version specified in the file name, you 
must open the file using BOTH and APPEND. 


+-(OPENFILE 'complex ‘input 'old) 
«KAISLER) COMPLEX. .9 


«(OPENFILE 'complex ‘input 'new) 
FILE WON'T OPEN 
COMPLEX 


The recognition modes are OLD, NEW, OLDEST, and OLD/NEW. When 
opening a file, INTERLISP first attempts to recognize the file (in the 
FULLNAME sense) using the specified recognition mode. If the file cannot be 
recognized for the given pair ({access mode), (recognition mode)), IN- 
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TERLISP returns the error message FILE NOT FOUND. Otherwise, the file is 
opened according to the access mode. : 

If the recognition mode is NIL, INTERLISP assumes a default based on the 
access mode. The current defaults are 


Access Mode Recognition Mode 
INPUT OLD 

OUTPUT NEW 

BOTH OLD/NEW 

APPEND OLD/NEW 


We can see that the functions discussed in the previous sections are special 
cases of the execution of OPENFILE. 


<(INFILE (file name)) 
is equivalent to 

«(INPUT (OPENFILE <file name) 'INPUT 'OLD)) 
and 

<-(OUTFILE <file name)) 
is equivalent to 

«(OUTPUT (OPENFILE <file name) 'OUTPUT 'NEW)) 


SIZE is used to determine the byte size in which to open the file. If it is NIL, 
the default value is used (for INTERLISP-10, it is 7; for INTERLISP-D, it is 8). 
A value of 7 results in the high-order bit of the byte being set to zero. This corre- 
sponds to the ASCII character instruction set. A byte size of 8 allows you to read 
all 8 bits of a standard byte; it is useful for processing EBCDIC files. 

The fifth parameter, PARMS, is used to specify a list of machine-dependent 
parameters. Currently, two parameters are supported by all versions of IN- 
TERLISP: 


WAIT wait if the file is busy 
DON'T.CHANGE.DATE don't change the access date 
INTERLISP-10 supports an additional parameter: 


THAWED open the file in the "thawed" 
mode 
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OPENFILE does not change the definition of the primary input or output 
files whereas INFILE and OUTFILE do. 
OPENFILE is not currently available in INTERLISP/370. 


Opening a File for Both Input and Output 

IOFILE is a function that opens a file for both input and output. As such, it is 
just another shorthand version of the more general OPENFILE. It takes the 
form ’ 


Function: IOFILE 

# Arguments: 1 

Argument: 1) a file name, FILE 

Value: The full name of the file if it is opened. 


IOFILE opens an existing file for both input and output, but does not 
change the current primary input or output files. 


«-(IOFILE 'complex) 
«KAISLER) complex. .9 


A Definition for IOFILE 
We might define IOFILE as follows: 


(DEFINEQ 
(iofile (file) 
(COND 
((FULLNAME file) 
(OPENFILE file 'BOTH 'OLD))) 


)) 


IOFILE is not currently available in INTERLISP/370. 


16.3.2 A Predicate for Testing Open Files 


INTERLISP provides a predicate for testing if a file is already open. This test is 
often required in multiprocessing environments or after an error has occurred 
(to prevent reinitialization of the file). OPENP expects a file name and an access 
mode. It returns the full name of the file if the file is open in the specified mode, 
but otherwise returns NIL. Thus, if the file is not recognized, OPENP will not 
generate an error. 

OPENP takes the following form 


Function: OPENP 
# Arguments: 2 
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Arguments: 1) a file name, FILE 
2) an access mode, ACCESS 
Value: The full name of the file. 


ACCESS may be INPUT, OUTPUT, or BOTH. If the access mode is NIL, 
then the file is validated for input or output, but not both. 


«-(OPENP 'presidents.lispin INPUT) 
[DSK]presidents.lispin;3 


«(OPENP 'presidents.lispin) 
NIL 


The latter case is a possibility if PRESIDENTS.LISPIN was opened in the 
BOTH access mode. 

If no file name is specified as an argument to OPENP, then OPENP returns 
a list of the open files, excluding T which is always opened by the system. Thus, 
if we executed the following commands, we would see 


«(INPUT (INFILE 'metro.1lisp) ) 
[DSK]metro.lisp;1 


<— (OPENP) 
([DSK]metro.lisp;1) 
° 


16.4 GETTING AND SETTING FILE ATTRIBUTES 


Most operating systems maintain a substantial amount of information about 
files in their directories. This information is used for different types of file man- 
agement operations. INTERLISP allows the user to obtain or set this informa- 
tion in order to determine how to manipulate files. 

GETFILEINFO is used for obtaining information about a file. It takes the 
following form 


Function: GETFILEINFO 
# Arguments: 2 
Arguments: 1) an S-expression specifying a file name, 
FILE 
.2) an attribute name, ATTRIBUTE 
Value: The current value of the attribute for the 


given file. 


INTERLISP accepts the following attribute names for all implementations: 
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Attribute Name Meaning 
WRITEDATE The data and time when the file was 
READDATE last written, last read, or 
originally 
CREATIONDATE created, respectively. 


Consider the following example: 


-(GETFILEINFO 'complex 'CREATIONDATE) 
"28-Jul-84 10:48:02" 


IWRITEDATE The integer form of the above 
IREADDATE attributes. 
ICREATIONDATE 


Consider the following example: 


«-(GETFILEINFO 'complex 'IREADDATE) 


12036747520 
BYTESIZE The byte size of the file. 
«-(GETFILEINFO 'complex 'BYTESIZE) 
a 
OPENBYTESIZE The byte size with which the file was 
opened. 
LENGTH The byte position of the end of the 
file (the file does not have to be 
opened) . 


Consider the following example: 


«(GETFILEINFO 'complex 'LENGTH) 
4522 
ACCESS The current access mode of the file; 
otherwise, NIL. 


IWRITEDATE, etc. are equivalent to applying the function IDATE to the 
value returned by GETFILEINFO for the corresponding attribute. 


«+ (GETFILEINFO 'COMPLEX 'IWRITEDATE) 
12036747270 


is equivalent to 
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+-(IDATE (GETFILEINFO <file name) WRITEDATE)) 
12036747270 


OPENBYTESIZE is provided because INTERLISP-10 allows you to open a 
file with a byte size different from its permanent byte size (that is, the one with 
which it was created). Note that INTERLISP-D assumes eight-bit bytes and cre- 
ates files in this manner. 

The information for all of these parameters is also stored in the file header 
written by INTERLISP using the File Package commands. 


INTERLISP-D Attributes 
The IRM [irm83] notes that INTERLISP-D distinguishes the type of the file 
using the following attribute: 


TYPE either TEXT or BINARY 


TEXT files are standard ASCII files while BINARY files are compiled code 
or files containing bit-map data for INTERLISP-D’s window support functions. 


INTERLISP-10 Attributes 
The IRM [irm83] notes that INTERLISP-10 running under TENEX or TOPS- 
20 will accept additional attributes. These are given below: 


SIZE The size of the file in pages. 
<(GETFILEINFO 'complex 'SIZE) 

2 

PROTECTION The "protection code" of the file; 


returned as an integer value. 


«-(GETFILEINFO 'complex 'PROTECTION) 
262080 


DELETED T, if the file has been ies 
otherwise, NIL. 


And for TOPS-20 


INVISIBLE T, if the file has the invisible 
attribute set; otherwise, NIL. 

ARCHIVED T, if the file has been archived; 
otherwise, NIL. 

OFF-LINE T, if the file's contents are off- 


line; otherwise, NIL. 
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Note that these attributes depend on specific features supported by the host 
operating system. For further explanation, you are encouraged to consult the 
manufacturer’s operating system manuals. 


16.4.1 Setting File Attributes 


The corresponding function for setting the values of file attributes is SETFILE- 
INFO, which takes the following form 


Function: SETFILEINFO 
# Arguments: 3 


Arguments: 1) a file name, FILE 
2) an attribute name, ATTRIBUTE 
3) a value, VALUE 


Value: T, if the attribute can be changed; 
otherwise, NIL. 


SETFILEINFO returns T if is successful in changing the value of the file’s 
attribute; otherwise, it returns NIL. Attribute values are defined by the host op- 
erating system. You should refer to the manufacturer’s manuals to determine 
what values may be changed. You should also note that the host operating sys- 
tem may support other file attributes that are not accessible by INTERLISP. 
Thus, you may have to perform some modification of the file’s attributes under 
the aegis of the host operating system’s command language or utilities. 


16.5 CLOSING FILES 


The corresponding operation to opening a file is closing it. INTERLISP provides 
three functions for closing files: CLOSEF, CLOSEF?, and CLOSEALL. 


16.5.1 Basic Closing Functions 
The general file close function is CLOSEF, which takes the form 


Function: CLOSEF 
CLOSEF? 
# Arguments: 1 
Argument: 1) a file name, FILE 
Value: The full name of the file it has closed; 


otherwise, NIL. 
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If the file is successfully closed, its name is returned as the value of CLO- 
SEF: 


“(CLOSEF 'presidents.lispin) 
[DSK]presidents.lispin;1 


If the file is not currently open, CLOSEF returns the error FILE NOT 
OPEN. : 


CLOSEF may be given a null argument. If so, it performs the following op- 
erations: 


- It attempts to close the primary input file if it is not T. 
. Failing that, it attempts to close the primary output file if it is not T. 
. Failing that, it returns NIL. 


. If either of operations 1 or 2 succeeds, the respective primary file is reset 
to T. 


> Ww N = 


CLOSEF? is an alternative form that closes the specified file if it is open. 
Otherwise, it returns NIL. That is, it does not generate an error, as CLOSEF 
does, if the files is not open. If it does succeed in closing the file, it returns the 
full name of the file as its value. 


16.5.2 Closing All Files 


Many applications open several files during their execution. When the execution 
terminates normally, good housekeeping requires that all files be closed to en- 
sure their integrity. The function CLOSEALL provides a means for closing all 
open files except T and any typescript file that is recording your session. The 
value returned by CLOSEALL is a list of files that have been closed. It takes the 
following form: 


Function: CLOSEALL 

# Arguments: 0 ) : 
Arguments: NIL 

Value: A list of files that it has closed. 


Consider the following example: 
«-(IOFILE 'COMPLEX) 
{KAISLER) COMPLEX. .9 


«-(IOFILE 'SHK) 
{KAISLER)SHK. .19 


———— 
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< (CLOSEALL) 
(<KAISLER) COMPLEX. .9 <KAISLER)SHK. .19) 


Note that certain files may be protected from the operation of CLOSEALL 
by the Whenclose Package, which is discussed in the next section. 


16.5.3 The Whenclose Package 


Closing a file is a serious matter in a program—one not to be taken lightly be- 
cause it removes all knowledge of the file from the system. It can be disastrous to 
close a file before you have updated it with the last changes to its contents. Also, 
if you have written a program that others may use, you may want to perform 
certain housekeeping operations on the file of which they should remain igno- 
rant. INTERLISP provides a convenient function for handling this problem, 
WHENCLOSE. 

WHENCLOSE is a function that assigns values to certain properties associ- 
ated with a file name that has been recognized by the system. These properties 
are inspected prior to closing the file (by any of the functions mentioned above or 
by a SYSOUT) to ensure that the appropriate actions are taken. 

The generic format for WHENCLOSE is 


Function: WHENCLOSE 
# Arguments: 3-11 


Arguments: 1) a file name, FILE 
2) a property name, PROPERTY 
3) a value for the property, VALUE 
4-11) repeat 2 & 3 by pairs 


Value: The full name of the file. 


WHENCLOSE is a nospread function. FILE must be the name of a file 
other than T (the terminal). If file is NIL, WHENCLOSE assumes you refer to 
the primary input and output files if they are other than T. 

WHENCLOSE currently recognizes the following properties: 


BEFORE 

The property value specifies a function that is to be executed immediately prior 
to the closing of the file. The function is passed the full name of the file as its 
argument by INTERLISP. For example, if you are writing a file by means of 
WRITEFILE, before you close it you may want to write the atom STOP at the 
end of the file. You can specify this operation as follows: 


<-(WHENCLOSE <filename) 'BEFORE (FUNCTION ENDFILE) ) 
« filename) 


516 File Management and Operations 


You may assign multiple BEFORE functions to a file, whence they will be 
executed in sequence of declaration. 


AFTER 

The property value specifies a function that is to be executed immediately after 
the file has been closed. The function is passed the full name of the file as its 
argument by INTERLISP. 

_ An application program may open and close files for you without your being 
aware that the program has done so. Sometimes, it is useful to reassure the user 
when a file has been closed successfully. Because WHENCLOSE uses CLOSEF, 
you are assured that the file was closed successfully if CLOSEF returns the file 
name. Thus, you can provide a function that notifies the user that the file has 
been closed. 


«-(WHENCLOSE <file name) 'AFTER (FUNCTION notify-user) ) 
< filename) 


<— (DEFINEQ 
(notify-user (filename) 
(PRIN1 filename) 
(PRIN1 '"' has been closed."') 
(TERPRI) 
)) 
(notify-user) 


You may assign multiple AFTER functions to a file, whence they will be 
executed in sequence of declaration. 


STATUS 

The property value specifies a function that is to be executed immediately prior 
to executing a SYSOUT. The value of the function is a list consisting of two 
parts: 


CAR-portion: The name of a function that is to be 
APPLY'd when the sysout file is 
restarted. 

CDR-portion: An S-expression to which the above 


function is APPLY'd to re-establish 
the status of the file. 


Thus, the function associated with the property value is expected to create 
the S-expression that is to be executed when the sysout file is reloaded for execu- 
tion. 

INTERLISP checks the value of the APPLY’d function. If it is NIL, IN- 
TERLISP assumes that the file’s status could not be restored. It prints a warning 
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message to the user and executes any functions associated with the file are exe- 
cuted. 


CLOSEALL 

The property value is either YES or NO. If it is YES, then this file may be closed 
by CLOSEALL (the function!). If it is NO, then CLOSEALL (the function!) will 
ignore the file. Thus, even though you use CLOSEALL to close all open files, you 
may protect some of them from its actions by assigning YES to this property for 
the respective files. 


EOF 

The property value specifies a function that is executed when an end-of-file con- 
dition is detected by INTERLISP. The function can determine what action to 
take given the condition and the state of the program. 

There are two exits from the specified function. A normal exit will cause the 
normal error handling machinery to be invoked by INTERLISP. Alternatively, 
you may use RETFROM (see Section 30.8) to return from the function, whence 
the error handling machinery is bypassed. Note that the file will not be closed if 
the EOF function does not close it. 

When a file is opened by INTERLISP, it is automatically initialized with the 
values of YES for the CLOSEALL property and CLOSEF for the EOF property. 


16.6 OTHER FILE OPERATIONS 


Most operating systems provide a rich set of functions for managing the file 
space of the user. INTERLISP provides access to the underlying operating sys- 
tem functions for deleting and renaming files. 


16.6.1 Deleting Files 


INTERLISP allows a user to delete a file by executing DELFILE, which takes 
the following form 


Function: DELFILE 

# Arguments: 1 

Argument: 1) a file name, FILE 
Value: The file name, if deleted; 


otherwise, NIL. 


In order to properly delete files, you usually must be specific about the ver- 
sion to be deleted. If the version is omitted, INTERLISP attempts to delete the 
oldest version of the file that is recognized in the directory. To delete a specific 
version, you must supply the version number as part of the file name. 
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+-(DELFILE 'COMPLEX) 
«KAISLER)COMPLEX. .6 


«-(DELFILE 'COMPLEX. .5) 
FILE NOT FOUND 
COMPLEX. .5 


because I have previously deleted it. 


16.6.2 Renaming Files 
You may rename a file using RENAMEFILE, which takes the following form 


Function: RENAMEFILE 

# Arguments: 2 

Arguments: 1) the old file name, OLD 
2) the new file name, NEW 

Value: The new file name if renaming is 
successful. 


If the version is omitted, RENAMEFILE attempts to rename the most recent 
version of the file found in the directory. The new file name is created with its 
version number set to 1. If the new file name already exists in the directory, 
RENAMEFILE returns NIL. 


«-(FULLNAME 'COMPLEX) 


{KAISLER) COMPLEX. .9 
*-(RENAMEFILE 'COMPLEX 'COMPLEXARITH) 
{KAISLER > COMPLEXARITH. .1 


+ (FULLNAME 'COMPLEX) 
(KAISLER) COMPLEX. .8 


where version 9 of COMPLEX was renamed to COMPLEXARITH. 


16.7 MANIPULATING FILE NAMES 


Each operating system has its own conventions for constructing file names, and 
for specifying them to file management functions. A full file name, as discussed 
above, consists of several fields. Dynamic construction of a file name can be a 
tedious process involving extensive string manipulation. It is often prone to er- 
ror, usually due to misplaced punctuation or field markers, that can lead to cata- 
strophic results for your files. INTERLISP provides several functions for manip- 
ulating file names. | 
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16.7.1 Unpacking a File Name 
You may unpack a file name using UNPACKFILENAME, which takes the form 


Function: UNPACKFILENAME 

# Arguments: 1 

Argument: 1) a file name, FILE 

Value: A list describing the fields and values of 


the file name. 


UNPACKFILENAME produces a list consisting of alternating field names 
and field values. The field values are the appropriate constituents of the given 
file name. 


<(UNPACKFILENAME 'presidents.lispin) 
(NAME presidents EXTENSION lispin) 


Note that UNPACKFILENAME does not attempt to recognize the file. 

The fields that may be produced by UNPACKFILENAME are HOST, DI- 
RECTORY, NAME, EXTENSION, and VERSION in INTERLISP-D. IN- 
TERLISP-10 recognizes the additional fields of PROTECTION, ACCOUNT, 
and TEMPORARY. 


<-(UNPACKFILENAME '{KAISLER)COMPLEX;9) 
(DIRECTORY KAISLER NAME COMPLEX VERSION 9) 


16.7.2 Constructing File Names 


You may construct a file name for submission to a file management function 
using PACKFILENAME, which takes the form 


Function: PACKFILENAME 
# Arguments: 2-N 


Arguments: 1) a field name, FIELD 
2) a field content, CONTENT 
3-N) pairs of field and content 


Value: A full file name. 


The argument to PACKFILENAME is a list consisting of alternating field 
names and field values. 
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+-(PACKFILENAME (LIST 'DIRECTORY 'lisp 
"NAME ''assertions" 
"EXTENSION 'lisp)) 

<lisp)assertions.lisp 


Note that the field values may be specified as either atoms or strings. 


16.7.3 Accessing a File Name Field 


Given a file name, you may want to extract a specific field. FILENAMEFIELD 
allows you to extract the field value from a file name. It takes the form 


Function: FILENAMEFIELD 

# Arguments: 2 

Arguments: 1) a file name, FILE 
2) a field name, FIELD 

Value: The value of the field for the given file 
name. 


INTERLISP recognizes the field names mentioned in Section 16.7.1. Con- 
sider the following example to retrieve the extension of a file: 


<(SETQ a-file-name 
(PACKFILENAME (LIST 'NAME ‘assertions 
"EXTENSION 'lisp))) 


assertions.lisp 


«-(FILENAMEFIELD a-file-name 'EXTENSION) 
lisp 


A special field value, BODY, allows you to splice values into the argument 
list to PACKFILENAME. Suppose that you merely wanted to change the direc- 
tory name of a file. You could use the following form: 


«-(SETQ new-directory 'kaisler) 
kaisler 


«(PACKFILENAME 'DIRECTORY new-directory 
'BODY a-file-name) 
(kaisler)assertions.lisp 


If the same field name is given twice in the argument list, INTERLISP uses 
only the first occurrence. Suppose you wanted to provide an extension to a file 
only if there is no current extension in the file name. You might use the following 
statement: 
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*-(SETQ a-file-name (LIST 'NAME 'assertions) ) 
(NAME assertions) 


+(SETQ a-default 'lispin) 
lispin 


<(PACKFILENAME 'BODY a-file-name 
"EXTENSION a-default) 
assertions.lispin 


This statement produces the given result because there is no extension speci- 
fied for the file name. 


16.8 RANDOM ACCESS FILES 


INTERLISP reads and writes most files as if they were serial byte streams. In 
this mode, a file is read starting from the initial byte. Successive bytes are ac- 
cessed in order until the last byte has been read. A file is written by sequentially 
placing bytes one after the other on the output stream until output is terminated. 
The length of the file is the number of bytes that currently reside in it. 

Serial files are not very efficient when the file is very large and only portions 
of its contents are required for processing. To remedy the situtaion, INTERLISP 
provides a limited random access capability to files. Underlying this mechanism 
is the notion of a file pointer. The value of the file pointer, when valid, corre- 
sponds to a byte location in the file. By assigning different values to the file 
pointer, you may specify the beginning address where data will be read from or 
written to. Thus, random accessing allows you to jump around the file gathering 
data from or scattering data to different locations. 

Unlike serial files, random access files require that you exercise additional 
caution: When you set the file pointer to the end of the file and begin to write, 
the file grows as succesisve bytes are placed in the output stream. It is possible to 
place the file pointer beyond the end of the file (by specifying a nonexistent byte 
address). When you commence writing, the bytes are placed at successive loca- 
tions beginning with the current value of the file pointer. However, a “‘hole”’ has 
been created, namely the sequence of bytes between the former end of the file 
and the new value of the file pointer. You may later write into these locations. If 
you do not, errors may result when you later attempt to read from them. 

Specifying a location in the file for writing will cause the new bytes to over- 
write the existing bytes. Careful control of where you read and write in a file 
must be exercised in order to prevent the obliteration of data. A number of au- 
thors have described random access techniques in considerable detail, including 
[knut68] and [wied77].. 

In the following sections, we discuss functions that allow you to manipulate 
the file pointer and randomly access files. 
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16.8.1 Manipulating the File Pointer 


You may get or set the file pointer. GETFILEPTR returns the current byte ad- 
dress in the file. The next input or output operation will begin at this location if 
the file pointer remains unmodified. 

GETEOFPTR returns the byte address of the last byte in the file. You may 
think of it as determining the length of the file (remembering that the first byte’s 
address is 0). These functions take the form 


Function: GETFILEPTR 
GETEOFPTR 
# Arguments: 1 
Argument: 1) a file name, FILE 
Value: The current or last byte address, 


respectively, of FILE. 


If the file is not open, both functions will generate an error “FILE NOT 
OPEN”’. Consider the following example: 


«-(OPENFILE 'JUNK 'OUTPUT 'NEW) 
{KAISLER) JUNK. .1 


«-(GETFILEPTR 'JUNK) 
0 


Now, let us write an expression to the file: 


«-(WRITEFILE (GETD 'COMPLEX) 'JUNK) 
{KAISLER) JUNK. .1 


«-(GETEOFPTR 'JUNK) 
370 


Setting the File Pointer 
SETFILEPTR allows you to modify the value of the file pointer. Three cases are 
possible: 


1. ADDRESS < 0, causes the file pointer to be set to the end of the file. 

2. 0 <= ADDRESS <¢ EOF, causes the file pointer to be set to the corre- 
sponding location. 

3. ADDRESS =) EOF, causes the file pointer to be set to the correspond- 
ing location, but a hole is created. The file is not enlarged until you actu- 
ally write data at the new location. 


SETFILEPTR takes the format 
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Function: SETFILEPTR 
# Arguments: 2 
Arguments: 1) a file name, FILE 
2) an address, ADDRESS 
Value: The new value of the file pointer. 


Consider the following example: 
«-(SETFILEPTR 'JUNK 100) 
100 

«(READ 'JUNK) 

(R I) 


which are the arguments to the function COMPLEX that was written to the file 
(see Section 13.7.2 for the full definition). 


«(READ 'JUNK) 
(¥ edited: "17-Jul-84 21:02") 


«-(GETFILEPTR 'JUNK) 
138 


16.8.2 Testing for Random Accessibility 


You may test whether or not a file is randomly accessible using RANDAC- 
CESSP, which takes the form 


Function: RANDACCESSP 

# Arguments: 1 

Argument: - 1) a file name, FILE 

Value: FILE, if it is randomly accessible; 


otherwise, NIL. 


Certain files are inherently not randomly accessible: T or NIL. Certain site- 
specific files (such as LPT) which correspond to psuedo-devices may also have a 
serial nature. FILE must be open or an error will be generated. 


«-(RANDACCESSP 'JUNK) 
{KAISLER) JUNK. .1 


<(RANDACCESSP T) 
NIL 
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16.8.3 Searching a File 


You may search a file for a specified pattern using either FILEPOS or FFILE- 
POS, which take the form 


Function: FILEPOS 
FFILEPOS 
# Arguments: 7 
Arguments: 1) a pattern, PATTERN 


2) a file name, FILE 

3) a starting address, START 
4) an ending address, END 

5) a wild card character, SKIP 
6) a tail flag, TAIL 

7) a case array, CASE 


Value: A byte address in FILE; otherwise, NIL. 


FILEPOS and FFILEPOS correspond to STRPOS (see Section 10.6) except 
that they search files rather than in-memory strings. 

(F)FILEPOS searches a file from START to END. If START is NIL, the 
current file pointer value is used. If END is NIL, the search will proceed to the 
end of the file. 

If the search is successful, the address of the byte sequence corresponding to 
PATTERN in the file is returned. If TAIL is T, the address of the first byte after 
the matching pattern is returned instead. If the search fails, NIL is returned. 
The file pointer is set to either of the byte addresses returned so that the next 
input or output operation may commence from that point. It is not modified if 
the search fails. ; 

SKIP is a character that matches any byte in the file at the corresponding 
location in PATTERN. 

Suppose we want to search the file JUNK for the sequence of characters 
(R I). We can use the following call: 


<(OPENFILE 'JUNK ‘INPUT 'NEW) 
(KAISLER) JUNK. .1 


«(FILEPOS '(R I) 'JUNK O NIL) 
102 


FFILEPOS differs from FILEPOS in that it uses a different search al- 
gorithm. The IRM [6.1.4] notes that FFILEPOS will be significantly faster for 
larger strings. You should consult the IRM for more details. 


Case Arrays 
Searching may distinguish between upper- and lower-case alphameric charac- 
ters or it may map several characters, which are usually ignored, into a single 


16.8 Random Access Files 525 


character. To do so, you must supply a case array, an array of 128 integers. Each 
byte in FILE that is to be matched will be mapped through CASE, if non-NIL, 
before matching. Character code i in FILE becomes j via (ELT CASE(ADD1 i)). 
You may create a case array using CASEARRAY, which takes the form 


Function: CASEARRAY 

# Arguments: 1 

Arguments: 1) An old case array address, OLDARRAY 
Value: The address of a new case array. 


CASEARRAY creates and returns the address of a new case array with all 
elements set to themselves to indicate the identity mapping. 


<(SETQ case1 (CASEARRAY) ) 
{ ARRAYP }#54.2621 


«(ELT casel 24) "INTERLISP-10"' 
23 


because INTERLISP-10 arrays begin at 1. 


Setting a Case Array 
You may set an element of a case array using SETCASEARRAY, which takes 
the form 


Function: SETCASEARRAY 
# Arguments: 3 


Arguments: 1) a case array address, CASEARRAYX 
2) a character code, FROMCODE 
3) a character code, TOCODE 


Value: The value of TOCODE. 


SETCASEARRAY inserts the value of TOCODE into the element given by 
FROMCODE in CASEARRAYX. Thus, when CASEARRAYX is used in a file 
search, all bytes having the value FROMCODE will be translated to TOCODE. 


Setting Break or Separator Characters 

If you do not want to match break or separator characters, SEPRCASE returns a 
case array in which all break or separator characters identified in FILERDTBL 
are mapped into the same character, a blank or space. SEPRCASE takes the 


following form 
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Function: SEPRCASE 

# Arguments: 1 | 

Argument: 1) a clisp flag, CLISPFLG 
Value: The address of a case array. 


The case array which is returned by SEPRCASE has all break and separator 
characters mapped into the character code 0. If CLISPFLG is not NIL, all 
CLISP characters are mapped into that same character as well. 


16.8.4 Copying Bytes from File to File 


You may copy bytes from one file to another using COPYBYTES, which takes 
the form 


# Arguments: 4 


Arguments: 1) a source file name, SRCFILE 
2) a destination file name, DSTFILE 
3) a starting byte address, START 
4) an ending byte address, END 


Value: T 


| 
| 
Function: COPYBYTES 


COPYBYTES generates an error “FILE NOT OPEN” if either or both of 
SRCFILE or DSTFILE are not open. 

COPYBYTES copies bytes from SRCFILE to DSTFILE beginning at 
‘START and continuing up to but not including END. If END is NIL, START is 
the number of bytes to be copied from SRCFILE’s current file pointer. If 
START is also NIL, bytes are copied from the current file pointer of SRCFILE to 
the end the file. Consider copying bytes from JUNK to the terminal: 


«(OPENFILE 'JUNK 'INPUT) 


{KAISLER) JUNK. .1 

<(COPYBYTES 'JUNK T 100 138) 
(R I) 

(* edited: ''17-Jul-84 21:02'') 
T 


«(COPYBYTES 'JUNK T 200 225) 
ORDACCESS (QUOTE REAL) | 
T | 


OPYBYTES begins copying at the exact byte that you specify. Thus, if you 
do properly specify a valid starting byte in the source file, you may put garbage 
into the destination file. 
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16.8.5 Testing for an End of File 


Before writing, you usually want to know if the file pointer is at the end of the 
file. EOFP allows you to test for an end of file. It takes the form 


Function: EOFP 

# Arguments: 1 

Argument: 1) a file name, FILE 

Value: T, if the file pointer points to the last 


byte in FILE. 


FILE must be open (at least for input) in order to test for the end-of-file 
condition. Consider the following example: 


«-(EOFP 'JUNK) 


NIL 

*+-(SETFILEPTR 'JUNK -1) 
-1 

<(EOFP 'JUNK) 

i 


16.9 SAVING AND RESTORING A USER’S VIRTUAL 
MEMORY 


Each INTERLISP user works with his own private memory. Because the IN- 
TERLISP address space is greater than most physical memories, a virtual mem- 
ory management scheme is used. However, this private memory is treated as a 
large linear name space. That is, a user may access any symbol defined within 
the name space. Partitions of symbols into collections are defined by the user 
according to the functions he has built or used. 

This linear name space means that, in most cases, a user may work profit- 
ably at only one problem at a time. However, many users tend to work on several 
problems. A linear name space prevents these different problems from having 
the same symbol names without conflict in meaning. 

In addition, only one copy of the virtual memory file is maintained on mass 
storage for each user. This virtual memory file is used to temporarily store por- 
tions of a user ‘s program until they are referenced by the CPU. A single copy of 
the virtual memory file is required because INTERLISP manages that file in a 
manner transparent to the user except for some small performance degrada- 
tions. 

If you are working on multiple independent problems, each problem should 
be physically separate in order to avoid name space conflicts. You may do this by 
creating separate copies of each problem’s environment (called saving). To rees- 
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tablish an evironment, you reload a copy into the INTERLISP virtual memory 
(called restoring). 
16.9.1 Saving Your Virtual Memory 


SYSOUT is used to save your private memory in a permanent disk file. SYSOUT 
takes the form 


‘Function: SYSOUT 
SYSOUTP 
# Arguments: 1 
Argument: 1) a file name, FILE 
Value: The value of FILE. 


FILE specifies the disk file where a copy of your INTERLISP environment 
will be saved. 


<(SYSOUT '(kaisler)aiwork.sysout) 
«KAISLER) AIWORK)SYSOUT. .1 


will save a copy of my current INTERLISP environment (which presumes an AI 
flavor) in the file AIWORK.SYSOUT in my current directory. 

If FILE is non-NIL, SYSOUTFILE is set to FILE. Normally, if FILE is NIL, 
the value of SYSOUTFILE will be used to store the virtual memory. The default 
value for SYSOUTFILE on INTERLISP-D is VIRTUALMEM. The default 
value for SYSOUTFILE in TENEX is WORK.EXE. If no extension is specified 
for the file name in FILE, the value of SYSOUT.EXT is used. It has the value 
SYSOUT for INTERLISP-D and EXE for INTERLISP-10 (TENEX). 

SYSOUT does not save the state of any open files. WHENCLOSE (see Sec- 
tion 16.5.3) may be used to specify the operations necessary to re-establish the 
file environment when the sysout is reloaded at a later time. 

SYSOUT returns NIL if the save operation fails for any reason; SHIRE: it 
returns the file name of the file which was created. 

Note: Failure may occur at the operating system level rather than within 
INTERLISP in which case SYSOUT never returns. For example, errors may 
result due to bad disk sectors, invalid virtual memory structure after a crash, or 
lack of sufficient disk space to accommodate the entire virtual memory file. 


Determining if a File is a SYSOUT 

You may determine whether or not a file that already exists was written by SYS- 
OUT by executing the predicate SYSOUTP. SYSOUTP takes one argument— 
the file name to be checked. SYSOUTP returns ? if the file was previously cre- 
ated by SYSOUT; otherwise, NIL. SYSOUTP is defined only for INTERLISP- 
10. . 
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In INTERLISP-10, SYSOUT saves only those portions of the virtual mem- 
ory which you have modified. Unchanged pages are retrieved from the makesys 
file of the INTERLISP system. This is because many users share a single com- 
mon makesys file in INTERLISP-10, which is a large, multi-user, timesharing 
system. 

In INTERLISP-D, a sysout file contains a copy of the entire allocated mem- 
ory. This is because Xerox 11xx machines are single-user workstations. For more 
information concerning the Xerox 11xx machines, consult the IRM. 


16.9.2 Restoring Your Virtual Memory 


You may restore an INTERLISP environment by executing the function SYSIN, 
which takes the form 


Function: SYSIN 

# Arguments: 1 

Argument: 1) a file name, FILE 
Value: The name of the file. 


SYSIN copies the environment contained in the argument file into the IN- 
TERLISP virtual memory. Execution begins immediately after the SYSOUT in- 
vocation. 


(SYSIN '<kaisler)aiwork.sysout) 


would restore my AI working environment. 

Note that SYSIN resumes execution immediately after the SYSOUT which 
created the permanent file. Thus, an expression of the following form would 
print the specified message upon return from a SYSIN: 


(PROGN 
(SYSOUT '<kaisler)aiwork.sysout) 
(PRIN1 "Hello, Steve!'') 
(TERPRI) 
(PRIN1 "Ready to begin work again, are you?") 
(TERPRI) ) 


would print, after a SYSIN, 


«+(SYSIN '(kaisler)aiwork.sysout) 
Hello, Steve! 
Ready to begin work again, are you? 
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SYSIN is defined for INTERLISP-10 only because it is a multi-user, time- 
sharing system. On INTERLISP-D, you may save and restore your virtual mem- 
ory from the default value of SYSOUTFILE unless multiple users share a single 
Xerox 11xx machine. Consult the IRM for details concerning loading sysouts 
under INTERLISP-D. 


16.9.3 Advising SYSOUT Before Saving 


SYSOUT is advised (see Chapter 21) to evaluate the S-expressions which are 
contained on BEFORESYSOUTFORMS. BEFORESYSOUTFORMS may 
contain expressions to 


1. Set SYSOUTDATE to (DATE) to record the time and date that the SYS- 
OUT was performed. 

2. If the argument is NIL, then the value of SYSOUTFILE is used as the 
destination of the SYSOUT. After the SYSOUT, SYSOUTFILE will be 
set to the value of the argument. SYSOUTFILE allows a user to issue the 
functional form (SYSOUT) for any saves subsequent to the initial one. 

3. Perform any operations associated with open files as specified by invoca- 
tions of WHENCLOSE (see Section 16.5.3). 

4. Any other S-expressions that you may wish to execute immediately prior 
to a SYSOUT necessary to record environmental information. 


Note that SYSOUT does not save the status of open files in an environment. 
Thus, you must record their status using the WHENCLOSE package prior to the 
SYSOUT in order that their status may be restored when the environment is 
restored. 

The initial value of BEFORESYSOUTFORMS is 


((SETQ SYSOUTDATE (DATE) ) 
(PROGN 
(COND 
((NULL FILE) 
(SETQ FILE SYSOUTFILE) ) 
(T 
(SETQ SYSOUTFILE 
(PACKFILENAME 'VERSION NIL 'BODY 
FILE) ) )) 
(COND 
( (AND 
(NULL (FILENAMEFIELD FILE 'EXTENSION) ) 
(NULL (FILENAMEFIELD FILE 'VERSION) ) ) 
(SETQ FILE 
(PACKFILENAME 'BODY 
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FILE 
"EXTENSION 
SYSOUT.EXT) )))) 
(RESTOREFILES T) ) 


16.9.4 Advising SYSOUT After Restoring 


After a SYSIN is completed, SYSIN is advised to execute the S-expressions con- 
tained on AFTERSYSOUTFORMS. Usually, AFTERSYSOUTFORMS will 
contain expressions to 


1. Reset the terminal line length to the appropriate value. 

2. Reset any terminal control characters (using RESETFORMS). 

3. If SYSOUTGAG is NIL, and the same user is executing the SYSIN as 
performed the SYSOUT, then the user is greeted with the value of 
HERALDSTRING followed by a greeting message. If the user perform- 
ing the SYSIN is different, INTERLISP prints the following message to 
the user: 


¥*** ATTENTION USER (userid): 

THIS SYSOUT US INITIALIZED FOR USER <other- 
userid) 

TO REINITIALIZE, TYPE (GREET). 


This allows the new user to execute his or her own personalized 
greeting file (see Section 29.5) to customize the environment for his or 
her work. 

If SYSOUTGAG is a list, the list is evaluated in lieu of printing the 
above messages. This allows a user to create and print his or her own 
greeting messages. 

If SYSOUTGAG is non-NIL and not a list (typically T), no message 
is printed. 

4. Invokes SETINITIALS to reset the user’s initials that are used for time- 
stamping (see Section 29.6.3). 

5. Perform any operations associated with previously opened files as speci- 
fied by invocations of WHENCLOSE (see Section 16.5.3). 


AFTERSYSOUTFORMS has the following structure: 


((SETQ TTYINEDIT.SCRATCH NIL) 
(RESTOREFILES ) 
(COND 
((LISTP SYSOUTGAG) 
(EVAL SYSOUTGAG) ) 
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(SYSOUTGAG) 
((OR 
(NULL USERNAME) 
(EQ USERNAME (USERNAME NIL T))) 
(TERPRI T) 
(PRIN1 HERALDSTRING T) 
(TERPRI T) 
(TERPRI T) 
(GREETO) 
(TERPRI T) 
(T 
(LISPXPRIN1 "**XXATTENTION USER " 


i 
(LISPXPRIN1 (USERNAME) 
T) 
(LISPXPRIN1 '"': this sysout is initialized for 
user" T) 
(LISPXPRIN1 USERNAME 
T) 
(LISPXPRIN1 " " T) 
(LISPXPRIN1 "To reinitialize, type GREET()" 
T))) 
(SETINITIALS) ) 


16.10 COMMENTING FUNCTION DEFINITIONS 


INTERLISP can be a difficult language to read, even when it is prettyprinted. 
Many users, hardened by experiences with previous conventional languages, 
tend to choose abbreviations or names for variables, properties, and functions 
that are often obscure and non-mnemonic. Even when mnemonic names are 
chosen for user variables, properties, and functions, the wealth of system vari- 
ables, properties, and functions (whose names tend to be non-mnemonic) can be 
quite confusing. 

To make source code readable and understandable, INTERLISP provides 
you with a flexible commenting feature that allows you to annotate functions and 
files. 

A comment is indicated by an S-expression beginning with the character *. 
It has the general form 


(* <comment text)) 


Comments are treated like other S-expressions. Thus, * is defined as an 
NLAMBDA, NOSPREAD function that merely returns its argument as its 
value. 
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Comments included in function definitions are part of the definition. Com- 
ments should be placed where they cannot affect the computation. Examples 
include 


1. Outside of COND expressions. 


2. If inside a COND expression (due to complexity or length), then within 
one of the COND cases. 

3. Outside logically complete S-expressions, particularly those that might 
take an indefinite number of arguments (as many File Package functions 
do). 

4. Outside of function definitions. 


Comments are intended mainly for documenting listings. When a function 
is prettyprinted at your terminal, comments are suppressed (presumably be- 
cause you know what you are doing—not always a good idea, though!). Instead, 
they are replaced by the string **COMMENT**. 


16.10.1 Printing Comments 


PRETTYPRINT (see Section 15.7.1) provides standard treatment for com- 
ments. In many cases, this suffices to meet your documentation needs. Some- 
times, you may want to emphasize a particular aspect of documentation. To do 
so, you need to display comments in a certain way. 

You may intercept comment printing from within PRETTY PRINT in order 
to perform special processing on the text. To do so, you must define * as a 
PRETTYPRINTMACRO: 


<(SETQ PRETTYPRINTMACROS 
'(* (LAMBDA (x) 
(RESETFORM (LINELENGTH 132) 
(COMMENTL x)))) 


which allows you to reset the line length, print the comment, and restore the line 
length. The form for a PRETTYPRINTMACRO is 


(<character) «function)) 


The function is defined as a LAMBDA expression taking one argument, X, 
which is the text of the comment as it occurs in the S-expression. You may pro- 
cess the string in any manner you choose before printing it. 

Comment printing is controlled by a system variable **COMMENT**FLG. 
If this variable is NIL, the entire text of the comment is printed by PRETTY- 
PRINT exactly as it appears in the S-expression. If it is non-NIL, PRETTY- 
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PRINT substitutes its value in place of the comment text in a list. Initially, 
**COMMENT**ELG is set to **COMMENT**. 


16.10.2 Comment Pointers 


When programs are heavily commented, considerable storage may be consumed 
to represent the comment text. Comments are needed only for documentation 
and are usually manipulated during editing. If many comments appear inside a 
function, each is evaluated as an S-expression even though it only returns the 
comment text as a value. A substantial penalty is paid for setting up the system 
stack each time a comment S-expression is evaluated. 

Rather than loading comment text into memory, INTERLISP creates a 
pointer to it in memory. This allows the comment to be retrieved from the file 
when necessary. Otherwise, it consumes a minimal amount of memory. 

You may enable this feature by resetting the system variable NOR- 
MALCOMMENTSELG to NIL. It is initially T meaning comment text is loaded 
into memory. 

You may get the comment text from a file by using GETCOMMENT, which 
takes the form 


Function: GETCOMMENT 

# Arguments: 2 

Argument: 1) a comment pointer, COMMENTPTR 
2) a destination file, DSTFIL 

Value: The value of COMMENTPTR. 


* is defined as a read macro (see Section 14.4) in FILERDTBL, the read 
table used by the File Package. When a * is encountered, the loading routines 
construct an expression containing 


1. The name of the file. 
2. The address of the first byte where the comment is located. 
3. The length of the comment text. 


Reading a Comment 

READCOMMENT is used to implement * as a read macro. It takes the form 
Function: READCOMMENT 
# Arguments: 3 


Arguments: 1) a file name, FILE 
2) a read table, RDTBL 
3) a list, LST 


onan pt aoa 


16.10 Commenting Function Definitions 535 


Consult Section 14.4.5 for the definition of read macros. 
* defined as a read macro appears as 


(10MACRO 
(X 
(AND 
(OR NCF PCF VCF) 
(COMPEM 
(CONS (LIST '* (CAR X) '' ) 
"(COMMENT USED FOR VALUE) ))) 
(KWOTE (CAR X))) . 
Printing a Comment 


On output, * is defined as a prettyprint macro. Its effect is to copy the comment 
text from one file to another. It is defined using PRINTCOMMENT 


Function: PRINTCOMMENT 

# Arguments: 1 

Argument: 1) a comment pointer, COMMENTPTR 
Value: The value of X. 


Thus, on PRETTYPRINTMACROS, we find 


<PRETTYPRINTMACROS 
((* . PRINTCOMMENT) ) 
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The File Package 


INTERLISP attempts to provide you with a wholly self-contained programming 
environment. To this end, it provides a comprehensive package of file manage- 
ment functions. This package treats a symbolic file as a database that may con- 
tain function definitions, variable values, and record declarations, among other 
data elements. The symbolic file serves as a repository for this information. To 
process it, you load the symbolic file (or portions of it) into memory. In one 
sense, INTERLISP provides you with the illusion of a single level of memory, 
although this is not fully implemented. 

The File Package is a set of functions, conventions, and interfaces for facili- 
tating the bookkeeping involved in developing and maintaining a large system 
comprised of many files—both code and data. The File Package is interfaced, at 
a lower level, to the host operating system under which INTERLISP executes. 
However, unlike most conventional operating systems, the File Package relieves 
the user of the burden of worrying about many trivial details concerning where 
data are located, what the structure of data is, and which files have been modi- 
fied. 


17.1 FEATURES OF THE FILE PACKAGE 


The File Package maintains knowledge of the functions and variables contained 
within the file. It also will maintain information on property lists, record decla- 
rations, edit macros, hash arrays, and other INTERLISP data structures. Asso- 
ciated with each file is an atom whose prefix is the file name and whose suffix is 
COMS. For example, a file describing an augmented transition network named 
ATN would have an atom named ATNCOMS. The -COMS atom is a list of com- 
mands that describe how to write out the file. 

The File Package provides functions for performing the following operations 
(which are described in the following sections) 
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Creating and destroying definitions of data structures associated with the 
file. 


Methods for augmenting the command list to include new items or deleting 
existing items. 

A method for determining whether or not an item of a given type resides on a 
file or any file. 

A method for determining what files, if any, contain definitions for a given 
type of data structure. 

A method for determining what files need to be updated to ensure a 
consistent permanent version of data structure definitions currently defined 
in memory. 


The File Package supports three categories of operations: 


1. Marking changes to files. 
2. Noticing the existence of files. 
3. Updating files. 


17.1.1 Marking Changes to Files 


Whenever an object is modified by a system function that appears in a File Pack- 
age command, that function invokes MARKASCHANGED (see Section 17.3.9) 
to mark the object as changed. For example, modifying the definition of a func- 
tion via EDITF causes that function to be marked as modified and of type FNS. 
The File Package needs to know what objects have been changed so it can prop- 
erly update the file on disk when a MAKEFILE is issued. 

The marking function’s effects are not always obvious, as evidenced by the 
following examples: 


Only those properties of an atom whose values have changed will actually be 
marked as changed. 

Changing the value of the property EXPR of an atom really effects a change 
in an object that would appear in an FNS command. 

Advising a function causes a change in the function’s definition that resis 
in it being marked as changed. 

Modifying a variable’s value by a program is not noticed by the File 
Package, and so must be explicitly declared. 


17.1.2 Noticing Files 


A file is noticed when it is referenced by a load function, an open function, by 
MAKEFILE, or when definitions are first associated with a file name via 
FILES? or ADDTOFILES?. The act of noticing causes the root file name to be 
added to FILELST. i’ Oh 
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The property FILE with value ((<filename)>COMS type)) is added to the 
property list of the root file name. “‘type”’ indicates how the file was loaded, e.g., 
what function was used to access it. When FILE appears on the property list of 
an atom, it implies that the corresponding file has been modified since the last 
time it was loaded or dumped. 


17.1.3 Updating Files 


UPDATEFILES is invoked, periodically, to determine which files contain those 
items that have been changed during the session. It scans FILELST. When (or 
if) any files are found that contain an item that has been changed, the name of 
the item is added to the property FILE on the root file name. After UPDATE- 
FILES has been executed, the files that must be dumped to ensure a permanent 
record of changes are just those files on FILELST whose FILE property CDR is 
non-NIL. 

Whenever a file is (re)written by MAKEFILE, all items that have been 
changed are removed from the FILE property list and placed on the FILE- 
CHANGES property list. The CDR of the FILE property is set to NIL. 


17.1.4 File Package Properties . 


The File Package keeps certain information about the status of a noticed file on 
the property list of the atom corresponding to the root file name. The following 
property names are used 


FILE When a file is noticed, the property FILE 
is added to the root file name's property 
list. It is given a value of 
((<filecoms). <loadtype))). <filecoms) is 
the name of the variable that contains 
the File Package commands for the file. 
{loadtype) indicates how the file was 
loaded into the INTERLISP environment 
(see Section 17.9). 


FILECHANGES This property contains a list of all 
changed items since the file was loaded. 
When the file is dumped, the changes in 
the CDR of the FILE property (see Section 
17.1.3) are added to the FILECHANGES 
property. 


FILEDATES This property contains a list of the 
version numbers and corresponding file 
dates for this file. The version numbers 
and dates are used when remaking a file. 
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FILEMAP This property stores a file map for the 
file. File maps are used to directly load 
individual functions from specific 
locations within the file. The following 
section discusses file maps in more 
detail. 


Consider the following example: 


«(LOAD 'FRAMES) 
(KAISLER) FRAMES. .18 


*-(GETPROPLIST 'FRAMES) 

(FILEDATES ((''11-Jul-84 19:50:48" . (KAISLER)FRAMES. .18) ) 
FILEMAP ({KAISLER)FRAMES..18 (NIL (664 7916 (CREATE.NODE 
676 . 926) (INITIALIZE.NODE 930 . 1941) ...))) FILE 
((FRAMECOMS . T))) 


where the ... indicates a lot of extraneous material. 


17.1.5 File Maps 


A file map is a data structure that describes the contents of a file. Within the 
filemap is a sequence of expressions that identifies each function, whether sym- 
bolically defined via DEFINE/DEFINEQ or compiled, and its beginning and 
ending byte addresses. These byte addresses may be used with SETFILEPTR to 
retrieve individual functions in the file. 

Many of the File Package functions depend on the file map for correct and 
efficient operation. Loading selecting functions via LOADFNS is accomplished 
by looking up each function in the file map and retrieving it using its beginning 
and ending byte addresses. When you remake a file, only the functions that have 
been changed are written from memory to the new version of the file. Unchanged 
functions are merely copied from the old version to the new one. 

A file map is created by MAKEFILE when it writes a new file. MAKEFILE 
assumes that the expressions that it is writing to the file are DEFINEQ forms. 
PRETTYPRINT, which actually writes the expressions to the file, must know 
that it is writing DEFINEQ expressions. Thus, you should never print a DE- 
FINEQ expression onto a file yourself, but always use the FNS command (see 
Section 17.2.1). 

File maps are written as the last expression on the file. The location of the 
file map is overwritten into the FILECREATED expression that appears at the 
beginning of the file. This allows rapid access to the file map without reading the 
entire file. 

Two variables affect the use and creation of file maps: 


BUILDMAPFLG If BUILDMAPFLG is set to NIL, a file map 
will not be built by LOAD or LOADFNS, or 


USEMAPFLG 
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written by MAKEFILE. Its initial value 
16:7 


When exporting symbolic files outside 
the INTERLISP environment, you may not 
want to include a file map. Setting 
BUILDMAPFLG to NIL allows you to omit 
these data in the file. 


If USEMAPFLG is T, the functions that 
normally use file maps check to see if a 
file map exists for the file that is to 
be operated upon. Three checks are 
performed: 


1. They check to see if a file map 
already exists in memory. 


2. If not, they check the FILECREATED 
expression to see if it has the 
address of a file map which can be 
read from the file. 


3. If not, they build a file map, unless 
BUILDMAPFLG is NIL. 


If USEMAPFLG is NIL, the FILEMAP 
property and the file will not be 
checked for the file map. This allows 
you to recover from errors or problems 
caused by operating upon symbolic files 
outside of the INTERLISP environment. 
The IRM suggests that editing a symbolic 
file that has a file map with a text 
editor by adding or deleting one 
character distorts the file map with 
(often) catastrophic results. 


The value of USEMAPFLG is initially NIL. 


17.1.6 File Package Variables 


The operation of the File Package is controlled by several variables. These are 


described below: 


FILEPKGFLG 


When you enter the INTERLISP 
environment, all File Package 
operations are normally enabled. 
Setting FILEPKGFLG to NIL disables the 
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noticing of files and marking of 
changes. However, the File Package 
functions will still operate, but their 
results are not guaranteed to be 
correct. 


FILELST Its value is a list of all files 
(actually, their root file names) that 
have been noticed by the File Package. 


Consider the following example: 


«-FILELST 

(FRAME COMPLEX) 

LOADEDFILELST Its value is a list of the actual names 
of all files that have actually been 
loaded by one of the File Package 
loading functions (see Section 17.9). 
This variable is not used by the File 
Package, but maintained by it so that 
you may determine which files have been 
loaded. 


Consider the following example: 


< LOADEDFILELST 
(<KAISLER)FRAME..19 <{KAISLER)COMPLEX.9) 


Note that FILELST and LOADEDFILELST are not affected by the func- 
tions CLOSEF or CLOSEALL described in Chapter 16. INTERLISP distin- 
guishes between files that have been opened for reading and writing and files 
that have been accessed to load functions. 

Using the File Package, you may consider that you have a virtually unlim- 
ited one-level memory. Functions may be stored in disk files and loaded as they 
are needed by other functions or programs. Unfortunately, the virtual storage 
limit of INTERLISP (all versions) prevents you from deleting functions in your 
environment once you have loaded them. The only solution is to save everything 
and reinitialize the environment. 


17.2 FILE PACKAGE COMMANDS" 


The <file)COMS atom is a list of commands that describe how a file is to be 
written when the appropriate function is executed. In effect, these commands 
determine how to update the contents of the file which represents a (more or less) 
permanent version of a portion of your INTERLISP environment. A wide variety 
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of commands are provided that allow the user to maintain a comprehensive rec- 
ord of his environment between INTERLISP sessions. This section describes the 
form and interpretation of each File Package command. 


17.2.1 Functions 


You may specify which function definitions are to be written to the file by adding 
a function command to the <file)COMS list. The function command is a list 
having the form 


(FNS function[1]..... function[N]) 


where ‘‘function[...]’’ are the names of functions whose definitions are to be 
written to the file. When the FNS command is interpreted, a DEFINEQ expres- 
sion is written to the file for the current function definition. For example, 


(FNS CLEANUP COMPILEFILES COMPILEFILESO CONTINUEDIT 
LISTFILES LISTFILES1 MAKEFILE MAKEFILES ADDFILE 
ADDFILEO) 


For each file name in an FNS command, new definitions of those functions 
will be written to the file when it is created. If the definition has been modified in 
memory after the function has been defined or loaded, that definition will be 
used. If the definition has not been modified, it will be copied from the existing 
file image on disk. 

Let us assume a file of functions that operate on points. We set up the FNS 
command as 


(FNS * POINTFNS) 
and define POINTFNS by 


(SETQ POINTFNS 
(LIST 'point.sum 'point.difference 'point.times 
'point.quotient 'point.radius 
'point.scaleby) ) 


When POINT is created by MAKEFILE, a definition for POINTFNS will 
be written to the file as follows: 


(RPAQQ POINTFNS 
(point.sum point.difference point.times 
point.quotient point.radius point.scaleby) ) 
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Each function will have a definition written to the file such that the function 
will be redefined when the file is loaded. The form of this definition is 


(DEFINEQ 
(point.sum ...) 
(point.difference ...) 


(point.scaleby ...)) 


where ... indicates the remainder of the function’s definition. 
MAKEFILE (see Section 17.3.1) uses the FNS command to build the file 
map. 


17.2.2 Variables 


You may write the values of variables to a file by including a variable command 
in the <file)COMS list. A variable command takes the following form: 


(VARS var[1]...var[N]) 
where the ‘‘var[...]’” may have one of two formats: 


1. If var[...] is an atom, then the value of the variable is written onto the file 
using the S-expression 


(RPAQQ var[...] value) 


2. If var[...] is not an atom, it is treated as an S-expression of the form 
(var[...] value-definition) and it is written onto the file using the S-ex- 
pression 


(RPAQ var[...] value-definition) 
Consider the following example: 


(VARS ( FONTCHANGEFLG) 
(LISTFILESTR (QUOTE "' ")) 
(FILELINELENGTH 72) 
(MAKEFILEREMAKEFLG T) 
(CLEANUPOPTIONS (QUOTE (LIST RC))) 
(#LISTFILESCHARS 110) ) 


In each of the instances above, the value of var[...] is not an atom, but an S- 
expression. Thus, the value will be written to a file with an RPAQ expression. 
Note that the value for FONTCHANGEFLG will be NIL. 
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Note that if you create a shorthand form of a command, such as (FNS * 
POINTENS) above, each variable containing the names of objects to be written 
to the file will have a VARS expression also placed in the file to re-establish its 
value. Thus, you should expect to see in your symbolic file an expression of the 
form 


(VARS POINTFNS) (RPAQQ POINTFNS (...)) 


Suppose we are creating a database in INTERLISP for a frame application. 
Each node in the net is represented by an atom. When we “‘save”’ the database 
via MAKEFILE (see Section 17.3.1), we want to place definitions in the file that 
will recreate the node when the file is loaded. To do so, we define the VARS 
variable as (assuming a database for the USA): 


(VARS * usavars) 
and set its value by 


(SETQ usavars 
(LIST 'maryland 'idaho 'virginia ...)) 


A definition for creating the value of USAVARS is written to the file as 


(RPAQQ usavars NIL) 
(ADDTOVAR usavars maryland idaho virginia ...) 


Each variable will be defined in the file by an expression of the form 


(RPAQ? maryland NIL) 
(RPAQ? idaho NIL) and so on. 


There are several variations on the VARS command that depend on the na- 
ture of the environment or the data. 

You may wish to specify variables in the form of a compiler declaration 
within the file. There are three commands that allow you do so: 


(SPECVARS vars[1] ... vars[N]) 
(LOCALVARS vars[1] ... vars[N]) 


(GLOBALVARS vars[1] ... vars[N]) 


Each of the variables associated with the commands is included in an ex- 
pression of the form 


(DECLARE: DOEVAL@COMPILE DONTCOPY var) 
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Ugly Variables 

In general, you may assume that each S-expression that is printed by IN- 
TERLISP may be read by INTERLISP in the same form. Some data structures 
exist for which a “read” operation is not the inverse of a “print” operation. 
These include arrays, read tables, and user-defined data types. To handle these 
variables, you may include the command 


(UGLYVARS var[1] ... var[N]) 

Suppose that you want to save the value of an array on a file so that it may 
later be read in. Let the name of the array be RBIS, and let the contents be 
expressions of the form 

(<year) . <rbis)) 


Let the array contents have the following form: 


«-(FOR I FROM 1 TO 5 (PRINT (ELT RBIS I))) 


(1971 . 53) 
(1972 . 55) 
(1973 . 38) 
(1974 . 9) 
(1975 . 41) 


To save the array in a file call RBISTATS, we need to create a variable 
RBISTATSCOM with the following value: 


«-(SETQ rbistatscom (LIST (LIST 'UGLYVARS 'RBIS))) 
((UGLYVARS RBIS) ) 


and we make the file using the following expression: 


«(MAKEFILE 'rbistats) 
{KAISLER)rbistats..1 


«-(PRINTDEF (READFILE 'rbistats) ) 
((FILECREATED "25-Aug-84 10:073;13" <(KAISLER)RBISTATS. .1 
313 changes to: (VARS RBISTATSCOMS RBIS) ) 
(PRETTYCOMPRINT RBISTATSCOMS) 
(RPAQQ RBISTATSCOMS ((UGLYVARS RBIS) )) 
(READVARS RBIS) 
({Y5 0 1 (1971 . 53) 
(1972 . 55) 
(1973 . 38) 
(1974 . 9) 
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(1975 . 41) 


[R5 5] 1) 
(DECLARE: DONTCOPY (FILEMAP (NIL) ))) 


READVARS is an implementation-dependent internal function used to 
read special forms from a file to ensure that they are properly recreated in your 
INTERLISP environment. 

Note that UGLYVARS does not do any checking for circular data struc- 
tures. If you know that your data structures do not contain any circularities, the 
IRM recommends that you use UGLYVARS to print unusual data structures to 
files because of the savings in execution time and internal storage usage. 


Horrible Variables 

Some data structures are inherently circular. Attempting to print them in the 
normal fashion may result in infinite loops. INTERLISP provides the HPRINT 
package (see Section 15.1.6) to handle the printing of circular structures. To 
print circular structures on the file, you may include the following command: 


(HORRIBLEVARS var[1] ... var[N]) 


which uses the HPRINT package rather than PRINT to write S-expressions on 
the file. 
Consider the following circular data structure: 


<(SETQ rare-gases 
(LIST 'helium 'krypton ‘argon 'xenon 'radon)) 
(helium neon krypton argon xenon) 


«-(RPLACD (LAST rare-gases) rare-gases) 
(helium neon krypton argon xenon ...) 


Suppose you want to put this list on a file called ELEMENTS. We create the 
File Package command variable as follows: 


<(SETQ ELEMENTSCOMS 
(LIST (LIST 'HORRIBLEVARS 'rare-gases) ) ) 
((HORRIBLEVARS rare-gases) ) 


«(MAKEFILE 'ELEMENTS) 
{KAISLER) ELEMENTS. .1 


«-(PRINTDEF (READFILE 'ELEMENTS) ) 
((FILECREATED ''25-Aug-84 10:22:54" (KAISLER)ELEMENTS. .1 
295 changes to: 

(VARS ELEMENTSCOMS RARE-GASES) ) 
(PRETTYCOMPRINT ELEMENTSCOMS ) 
(RPAQQ ELEMENTSCOMS ((HORRIBLEVARS RARE-GASES) ) ) 
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(READVARS. RARE-GASES) 
(T (HELIUM NEON KRYPTON ARGON XENON . [1])) 
(DECLARE: DONTCOPY (FILEMAP (NIL) ))) 


Initializing Variables 

When you load a file into your INTERLISP environment, it may contain defini- 
tions for variables that may also have been defined in previous files. By loading 
the new file, you would overwrite those previous definitions with the values con- 
tained in VARS commands in the new file. To prevent this, you would have to 
carefully structure your file loading sequence to ensure that variable definitions 
are not repeated in more than one file or, if they are, do not cause damage by 
overwriting one another. INTERLISP provides a File Package command to as- 
sist in this process. 

You may cause a variable to be defined during file loading only if the current 
value of the variable is NOBIND in the environment (meaning it is undefined). 
To do so, you include an initialize variables command in your (file)COMS list. 
It takes the form 


(INITVARS var[1] ... var[N]) 


Variables specified in an INITVARS command will have their values de- 
fined when a file is loaded, if and only if the variable has the value NOBIND in 
the environment. Thus, if the variable already has a value in the environment, its 
value will not be changed. 

INITVARS causes an RPAQ? expression to be written on the file instead of 
an RPAQ expression. 


17.2.3 Adding Variables to a File 


Once a file is established, you may wish to add new values to those currently 
defined for variables in the file. To do so, you include an add-to-variable com- 
mand in the <file)COMS list. It has the format 


(ADDVARS (var[1] . lst[{1]) 
(var[N] . lst[N])) 


Each sublist (var . Ist) writes an S-expression on the file. For each variable, if 
there is a value in LST that is not a member of the current value of the variable 
when the file is loaded, that value will be added to the value of the variable. The 
new value of the variable is the union of its old value from the file and the value to 
be added as a result of the ADDVARS expression. An example of an ADD- 
VARS expression is 


(ADDVARS (FILELST) 
(LOADEDFILELST) 
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(CFILELST) 
(NOTLISTEDFILES) 
(NOTCOMPILEDFILES) 
(MAKEFILEFORMS 
(COND 
((MEMB 'NOCLISP OPTIONS) 
(RESETSAVE PRETTYTRANFLG T) ) 
((MEMB 'CLISP% OPTIONS) 
(RESETSAVE PRETTYTRANFLG 'BOTH)) ) 
(COND 
((MEMB 'FAST OPTIONS) 
(RESETSAVE PRETTYTRANFLG NIL))) 
(COND 
((OR 
(MEMBER 'CLISPIFY OPTIONS) 
(MEMBER 'CLISP OPTIONS) ) 
(RESETSAVE CLISPIFYPRETTYFLG T)) 
((OR 
(EQ FILETYPE 'CLISP) 
(MEMBER 'CLISP (LISTP FILETYPE)) ) 
(RESETSAVE CLISPIFYPRETTYFLG 
'CHANGES) ) ) 
(AND 
(NEQ (LINELENGTH) FILELINELENGTH) 
(RESETSAVE (LINELENGTH 
FILELINELENGTH) ) )) 
(MAKEFILEOPTIONS RC C LIST FAST CLISP 
CLISPIFY NIL 
REMAKE NEW NOCLISP CLISP% F 
ST STF 
(REC . RC) 
(BREC . RC) 
(TC' 4.€) 
(BG . ©) 
(TCOMPL . C) 
(BCOMPL . C)) 
(NILCOMS) ) 


If LST is not specified, the variable is initialized to NIL if its current value is 
NOBIND. This prevents errors of the form UNBOUND ATOM that might oc- 
cur later in your program where you assumed the variable had been initialized to 
some value. 

Consider the rare gases example from the last section. Let us add the gas 
RADON to the list of RARE-GASES. To ensure that the variable is properly 
updated, we add the following expression to ELEMENTSCOMS: 
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(ADDVARS (RARE-GASES . RADON) ) 
You may do this as follows: 


(SETQ ELEMENTSCOMS 
(APPEND ELEMENTSCOMS 
(LIST 
(LIST 'ADDVARS 
'(RARE-GASES . RADON) )))) 
((HORRIBLEVARS RARE-GASES) (ADDVARS (RARE-GASES . RADON))) 


«(MAKEFILE 'ELEMENTS) 
<KAISLER)elements. .2 


<-(PRINTDEF (READFILE 'ELEMENTS) ) 
((FILECREATED "25-Aug-84 10:52:05" (KAISLER)ELEMENTS. .2 
432 changes to: 
(VARS ELEMENTSCOMS RARE-GASES) 
previous date: "25-Aug-84 10:22:54" {(KAISLER)ELEMENTS. .1) 
(PRETTYCOMPRINT ELEMENTSCOMS ) 
(RPAQQ ELEMENTSCOMS ((VARS RARE-GASES) ) 

(ADDVARS (RARE-GASES RADON) ) ) 
(RPAQQ RARE-GASES (HELIUM NEON KRYPTON ARGON XENON) ) 
(ADDTOVAR RARE-GASES RADON) 
(DECLARE: DONTCOPY (FILEMAP (NIL) ))) 


«(LOAD 'ELEMENTS) 

(KAISLER) ELEMENTS. .2 

FILE CREATED 25-Aug-84 10:52:05 
ELEMENTSCOMS 

(KAISLER) ELEMENTS. .2 


“RARE-GASES 
(radon helium neon krypton argon xenon) 


where RADON was added to the front of the list of rare gases by the ADD- 
TOVAR expression contained within the file. 


17.2.4 Association Lists 


The association list command allows you to specify a set of association lists. Its 
format is 


(ALISTS (alist[1] atom ...) 


(alist(N] atom... )) 
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Each alist is the name of an association list. That is, a variable whose value 
is an association list. The atoms are the CARs of the association list entries. For 
each atom found in an association list, its definition will be written to the file if 
the atom is found on the association list. The expression written to the file en- 
sures that the association list will be recreated when the file is loaded. 

Consider the association list GAMES: 


<(SETQ games 
(LIST (CONS 'bridge 'cards) 

(CONS 'baccarat 'cards) 

(CONS 'chess 'pieces) 

(CONS 'craps 'dice) 

(CONS 'scrabble 'tiles))) 
((bridge . cards) (baccarat . cards) (chess . pieces) 
(craps . dice) (scrabble . tiles) ) 


Let us write the card games to a file called CARDGAMES. We set up the 
File Package command as follows: 


<(SETQ cardgamescoms 
(LIST 
(LIST 'alists '(games bridge baccarat) ))) 
((ALISTS (GAMES bridge baccarat) ) 


«(MAKEFILE 'cardgames) 
«KAISLER)CARDGAMES. .1 


<-(PRINTDEF (READFILE 'cardgames) ) 
((FILECREATED "25-Aug-84 11:04:35" <(KAISLER)CARDGAMES. .1 
285 changes to: 

(VARS CARDGAMESCOMS) ) 
(PRETTYCOMPRINT CARDGAMESCOMS ) 
(RPAQQ CARDGAMESCOMS ((ALISTS (GAMES BRIDGE BACCARAT) ))) 
(ADDTOVAR GAMES (BRIDGE . CARDS) 

(BACCARAT . CARDS) ) 

(DECLARE: DONTCOPY (FILEMAP (NIL)))) 


Note that when CARDGAMES is loaded, the card games (namely, 
BRIDGE and BACCARAT) are added to the current value of the variable 
GAMES. Thus, you may incrementally build the value of a variable by loading 
different files. 


17.2.5 Properties 


You may save the values of properties of atoms by including a property com- 
mand in the <filey)COMS list. The format of this command is 
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(PROP propname atom[1] ... atom{N]) 


A PUTPROPS expression (see Section 7.3) is written onto the file for each 
atom in the command that has the specified property. When the file is loaded, 
the effect of this command is to restore the value of the property for each atom. 

If PROPNAME is a list, PUTPROPS expressions will be written for each 
property in the list. If PROPNAME has the value ALL, then all of the properties 
of each atom will be saved in the file. 

Consider the following example in which we have defined several properties 
for states. We want to save just the GOVERNOR property of VIRGINIA, but all 
of the properties of MARYLAND. The File Package command is defined as 
follows: 


<(PUTPROP 'virginia 'governor 'robb) 
robb 


«-(PUTPROP 'maryland 'governor 'hughes) 
hughes 


«-(PUTPROP 'maryland 'capitol 'annapolis) 
annapolis 


«-(PUTPROP 'maryland 'senators '(mathias sarbanes) ) 
(mathias sarbanes) 


Let us save this information in a file called STATES. The File Package com- 
mand is set up as follows: 


<(SETQ statescoms 
(LIST 
(LIST 'PROP 'GOVERNOR 'VIRGINIA) 
(LIST 'PROP 'ALL 'MARYLAND) ) ) 
((PROP GOVERNOR VIRGINIA) (PROP ALL MARYLAND) ) 


«(MAKEFILE 'STATES) 
{KAISLER)STATES..1 


<(PRINTDEF (READFILE 'STATES) ) 
((FILECREATED "25-Aug-84 21:54:15" (KAISLER)STATES. .1 
472 changes to: 

(VARS STATESCOMS) ) 
(PRETTYCOMPRINT STATESCOMS) 
(RPAQQ STATESCOMS ((PROP GOVERNOR VIRGINIA) 

(PROP ALL MARYLAND) ) ) 

(PUTPROPS VIRGINIA GOVERNOR ROBB) 
(PUTPROPS MARYLAND GOVERNOR HUGHES CAPITOL ANNAPOLIS 
SENATORS (MATHIAS SARBANES) ) 
(DECLARE: DONTCOPY (FILEMAP (NIL) ))) 
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If an atom does not have the specified property, the File Package prints a 
warning message ‘““NO propname PROPERTY FOR atom’’. Note that if the 
atom has the property but its value is NIL, a PUTPROPS expression will be 
generated for that property. 

An alternative version of the property command will save only the properties 
that actually appear on the property list of the corresponding atom. Thus, while 
PROP causes a NIL to be written if the value of the property for a given atom is 
NIL, IFPROP will produce a PUTPROPS expression only if the property explic- 
itly appears on the atom’s property list. The format of IFPROP is 


(IFPROP propname atom[1] ... atom[N]) 


where the parameters have the same values as the PROP command. 

Another version of the property command is PROPS. PROPS specifies pairs 
of atoms and properties where each atom will have its associated property writ- 
ten to the file via a PUTPROPS expression. The format is 


(PROPS (atom[1] propname[1]) 
ate [N] propname[N}]) ) 


where the CDR of each sublist is the property of the atom whose value is to be 
saved in the file. Note that each of the atoms must be a LITATOM. 


17.2.6 S-expressions 


You may specify arbitrary S-expressions to be written to the file using the print 
command. Its format is 


(P expression[1] ... expression[N]) 


Each S-expression following P will be printed on the output file. Each S- 
expression will be evaluated when the file is loaded. 

Suppose we want to initialize application program menus when a file is 
loaded. We may set up the print commands as follows: 


(P 
(SETQ data.management.menu 
(create.data.management.menu) ) 
(SETQ database. functions.menu 
(create.database.functions.menu) ) 
(MASTERSCOPE 'ERASE) 
(SETQ COMMENTFONT (COPY BOLDFONT) ) 


io) 
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Each of the expressions is written to the file just prior to the file map. They 
are the last expressions read from the file. Each expression is evaluated as it is 
read, and thus sets the corresponding variable. 

Since these expressions are evaluated as they are read in, you may cause a 
program to be initiated by reading in a file. This has the effect of placing the user 
of the program in a specific environment governed by the program. 


17.2.7 Evaluation of S-expressions 


You may specify arbitrary S-expressions to be evaluated when a MAKEFILE is 
executed by including an evaluation command in the <file)COMS list. When 
MAKEFILE encounters an evaluation command, it evaluates the expressions 
following it. This command is useful for determining whether or not certain data 
should be written to the file. Evaluation commands may appear anywhere in the 
<file)COMS list, so they may be used to control whether or not other commands 
are executed based on the current state of your application. one format of an 
evaluation command is 


(E expression[1] ... expression[n]) 


For example, hash arrays have an internal format that is difficult to repre- 
sent as an S-expression. Rather, we would like to save expressions on the file that 
allow us to recreate the hash arrays when the file is loaded. We may do so using 
the following forms: 


(E 
(DMPHASH CLISPARRAY) 
(DMPHASH SYSHASHARRAY) ) 


which places PUTHASH expressions for creating all of the non-NIL entries of 
the hash array on the file. 


17.2.8 Commands 


You may specify arbitrary lists as commands by including a command command 
in the <file)COMS list. Its format is 


(COMS command[1] ... command[N]) 
where each command[...] will be interpreted as a File Package command when 


this command is encountered by MAKEFILE. 
Here is an example of how a COMS File Package command might appear: 


(COMS 
(FNS DO? DO?= ERRORCONTEXT WHY WHYO WHYSETUP WHYSPACE 
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WHYVARS GETARG# EXPLAIN1 EXPLAINARG EXPLAINARG1 
EXPLAINARG2) 
(VARS ORDINALS (LAST?) ) 
(P (SETSYNTAX (QUOTE ?) 
(QUOTE (INFIX FIRST NOESC DO?)) 
T) 
(SETSYNTAX (QUOTE ?) 
(T EDITRDTBL) ) 
(ADDVARS (LISPXHISTORYMACROS (? (WHY LISPXLINE) )) 
(LISPXCOMS ?)) 
(USERMACROS ?=) ) 


17.2.9 Comments 


You may include comments in your file by including a comment command in the 
(file)COMS list. Its format is 


(* . text) 


where ‘“‘text”’ is the comment to be printed in the file. 
For example, let us amend the File Package command variable STATES- 
COMS to read as follows: 


((* SAVE ONLY THE GOVERNOR OF VIRGINIA) 
(PROP GOVERNOR VIRGINIA) 

(* SAVE ALL OF MARYLAND'S PROPERTIES) 
(PROP ALL MARYLAND) ) 


Then, after making the file and printing it back, we see the following for- 
mat: 


<-(PRINTDEF (READFILE 'STATES) ) 
((FILECREATED "25-Aug-84 21:54:15" (KAISLER)STATES. .1 
472 changes to: 
(VARS STATESCOMS) ) 
(PRETTYCOMPRINT STATESCOMS) 
(RPAQQ STATESCOMS ((* SAVE ONLY THE GOVERNOR OF VIRGINIA) 
(PROP GOVERNOR VIRGINIA) 
(* SAVE ALL OF MARYLAND'S PROPERTIES) 
(PROP ALL MARYLAND) ) ) 
(* SAVE ONLY THE GOVERNOR OF VIRGINIA) 
(PUTPROPS VIRGINIA GOVERNOR ROBB) 
(* SAVE ALL OF MARYLAND'S PROPERTIES) 
(PUTPROPS MARYLAND GOVERNOR HUGHES CAPITOL ANNAPOLIS 
_ SENATORS (MATHIAS SARBANES) ) 
(DECLARE: DONTCOPY (FILEMAP (NIL) ))) 
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Comments are ignored when the file is loaded, so they help merely to explain 
the contents of the file. I urge you to place as many comments as you can in your 
files to help both yourself and others read them. 

If the first element of TEXT is a *, then MAKEFILE prints a form-feed on 
the file before printing the comment. This allows you to place page breaks within 
the file so that it is neatly formatted for later printing. 


17.2.10 Advice 


You may specify that functions that are “‘advised’’ when the file is created will 
return to that state when the file is loaded. To do so, you include an advised 
command on the <file)COMS list. Its format is 


(ADVISED function[1] ... function[N]) 


An appropriate expression will be written on the file to reinstate the “‘ad- 
vised” state of the function when the file is loaded. 

To reinstate the ‘‘advice”’ associated with the function, you may include an 
advice command in the <file)COMS list. Its format is 


(ADVICE function[1] ... function[N]) 


A PUTPROPS expression will be written to the file for each function that 
will put the advice onto its property list when the function is loaded. To reinstate 
the ‘“‘advised”’ state of the function, you may execute READVISE in lieu of in- 
cluding advise commands. 

Suppose we advise the function REAL as follows: 


“(ADVISE 'REAL 

"BEFORE 

"FIRST 

'(PRINT 'Invoking RECORDACESS"’) ) 
REAL 


Now, let us make sure the function is really advised by asking it to work on a 
complex number (see Section 13.7.2). 


+-(SETQ x (COMPLEX 1.0 3.0)) 
"Invoking RECORDACCESS" 
((1.0: . 3:0)) 


We obtain this output because we defined a DEFPRINT expression for 
complex numbers which is described in Section 13.7.2. In order to do the print- 
ing, we must access the REAL portion of the complex number we created, so we 
see that REAL has been advised. 


17.2 File Package Commands 557 


Let us write the advised function to a file called TEST. The File Package 
commands appear as follows: 


<-(SETQ testcoms 
(LIST 
(LIST 'FNS 'REAL) 
(LIST 'ADVISE 'REAL))) 
((FNS REAL) (ADVISE REAL)) 


Now, let us create the file TEST with the definition of REAL and its advice 
via 

“(MAKEFILE 'TEST) 

{KAISLER)TEST. .1 


«-(PRINTDEF (READFILE 'TEST)) 
((FILECREATED "25-Aug-84 22:01:20" <{KAISLER)TEST. .1 
609 changes to: 

(VARS TESTCOMS) 

(ADVICE REAL) ) 
(PRETTYCOMPRINT TESTCOMS) 
(RPAQQ TESTCOMS ((FNS REAL) 

(ADVISE REAL) 
(ADVICE REAL) )) 

(DEFINEQ (REAL 

(LAMBDA (X) 

(* edited: "17-Jul-84 21:03:34") 
(RECORDACCESS (QUOTE REAL) 
CX NIL (QUOTE FETCH))))) 

(PUTPROPS REAL 

READVICE 

(NIL (BEFORE FIRST 

(PRINT "Invoking RECORDACESS"") ) ) ) 
(READVISE REAL) 
(DECLARE: DONTCOPY 

(FILEMAP (NIL (218 384 (REAL 230 . 381))))) 


Note that when you specify an ADVISE File Package command, IN- 
TERLISP automatically readvises the function when the file is loaded by writing 
a call to READVISE into the file. If you use ADVICE instead, then the advice is 
place on the function’s property list, but you must explicitly readvise the func- 
tion. 


17.2.11 Macros 


INTERLISP provides three types of macro definitions. The File Package pro- 
vides commands for writing each type of macro definition to a file. 
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To save user macros, you may include a user macro command in the (file)- 
COMS list. Its format is 


(USERMACROS atom[1] ... atom[N]) 


where each atom corresponds to a user edit macro. An S-expression is written to 
the file to add the edit macro definition to USERMACROS. An S-expression 
will also be written to place the atom name on the appropriate spelling lists. 

To save “‘lispxmacros”, you may include a lispx macro command in the 
(file)COMS list. Its format is 


(LISPXMACROS atom[1] ... atom[N]) 


Each atom is either a “‘lispxmacro”’ or a “‘lispxhistorymacro” (see Section 
25.2.1). An expression will be written to the file which saves the definition of the 
macro so that it may be restored when the file is loaded. An expression will also 
be written to the file to add the macro definition to LISPXCOMS. 

You may save the MACRO properties of an atom by including a macro com- 
mand in the <file)COMS list. Its format is . 


(MACROS atom[1] ... atom[N]) 


For each atom, an expression will be written that embeds the macro prop- 
erty in a form of the following type: 


(DECLARE: EVAL@COMPILE atom) 


where these expressions are used by the compiler. 
Consider the usermacro M. We would place an entry in the <file)COMS list 
to save M as follows: 


(USERMACROS M) 


In the file, an expression to add the definition of M to USERMACROS, the 
variable, would appear as 


(ADDTOVAR USERMACROS 
(mM (X . Y) 
(E (MARKASCHANGED (COND 
((LISTP (QUOTE X)) 
(CAR (QUOTE X))) 
(T (QUOTE X))) 
(QUOTE USERMACROS) ) 
T) 
(ORIGINAL (MX . Y)))) 
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17.2.12 File Package Commands 


You may save user-defined file package commands or types in a file by including 
a user file package command in the file) COMS list. An S-expression is written 
to the file that restores the definition of the command or type when the file is 
loaded. Its format is 


(FILEPKGCOMS atom[1] ... atom[N]) 


For example, several of the File Package commands are defined in terms of 
other commands. Here are several: 


(FILEPKGCOM 
'MACROS 
'MACRO 
t (X 
(DECLARE: 
EVAL@COMPILE 
(PROPS * 
(MAPCAR 
(QUOTE X) 
(FUNCTION (LAMBDA (Y) 
(CONS Y 
(OR 
(INTERSECTION 
(PROPNAMES Y) 
MACROPROPS) 
(CAR 
MACROPROPS) )))))))) 


17.2.13 Records 


You may save the declarations of record types on the file by including a record 
command in the <filey)COMS list. Its format is 


(RECORDS record[1] ... record[N]) 


where each record [...] is the name of a record declaration. An S-expression is 
written to the file that will establish the record declaration when the file is 


loaded. 
Consider the definition of a complex number whose data structure was de- 


fined as a record (see Section 13.7.2). The File Package command for saving this 
data structure is 


(RECORDS COMPLEX) 
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and the expressions appearing in the file that redefines the record when the file is 
loaded is 


(DECLARE: EVAL@COMPILE (DATATYPE COMPLEX ((REAL FLOATP) 
(IMAG FLOATP) ))) 


(/DECLAREDATATYPE (QUOTE COMPLEX) 
(QUOTE (FLOATP FLOATP) )) 


17.2.14 Arrays 


You may save the definitions of arrays by including an array command in the 


<file)COMS list. Its format is 
(ARRAY variable[1] ... variable[N]) 


Each variable[...] should have an array specification as its value. An S-ex- 
pression is written to the file that will re-establish the array specification when 
the file is loaded. this expression also resets the contents of the array to the 
proper values as they were when the file was written. 

For example, let us define an array X and initialize it as follows: 


«(SETQ X (ARRAY 5 0 5)) 
{ ARRAYP }#526641 


«(FOR I FROM 1 TO 5 DO (SETA X I (RAND I (PLUS I 100)))) 
NIL 


«(FOR I FROM 1 TO 5 DO (PRINT (ELT X I))) 
14 
45 
69 
43 
35 
NIL 


Now, we can save X in a file TEST by defining its File Package commands to 
be 


<(SETQ TESTCOMS (LIST (LIST 'ARRAY 'X))) 
((ARRAY X)) 


Then, we can make the file and inspect it as follows: 


«(MAKEFILE 'TEST) 
{KAISLER)TEST..1 
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<(PRINTDEF (READFILE 'TEST) ) 
((FILECREATED "25-Aug-84 22:49:35"! (KAISLER)TEST. .1 
346 changes to: 
(VARS TESTCOMS X)) 
(PRETTYCOMPRINT TESTCOMS) 
(RPAQQ TESTCOMS ((ARRAY X))) 
(RPAQ X (READARRAY 5 (QUOTE 0) 1)) 
(14 45 69 43 3575555 5) 
(DECLARE: DONTCOPY (FILEMAP (NIL)))) 


Note that READARRAY is an internal, implementation-dependent func- 
tion that reads array definition data and values from a file. 


17.2.15 CLISP Expressions 


You may save CLISP expressions that define new iterative statement operators 
in a file by including a clisp command in the <file)COMS list. Its format is 


(I.S.OPRS operator[1] ... operator[N]) 


An S-expression is written to the file that redefines the value of the user- 
defined “‘i.s.opr’’ when the file is loaded (see Section 23.5). 


17.2.16 Templates 


You may save MASTERSCOPE templates in the file by including a template 
command in the <file)COMS list. Its format is 


(TEMPLATES atom[1] ... atom[N]) 
Each atom must have a MASTERSCOPE template (see Section 26.6). An S- 


expression is written to the file that restores the template when the file is loaded. 


17.2.17 Blocks 


You may save the definitions of blocks that are used by the compiler’s block 
compile function in the file by including a block command in the ¢filey)COMS 
list. Its format is 


(BLOCKS block[1] ... block[N]) 


For each block[...], a DECLARE expression is written to the file that will be 
used by the block compile functions. 
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17.2.18 Declarations 


Expressions written to a symbolic file are either evaluated when the file is loaded, 
copied to the compiled file when the file is compiled (see Section 31.2), or not 
evaluated at compile time. You may determine when an expression is to be eval- 
uated by including a declaration command in the <file)COMS list. Its format is 


(DECLARE: tag[1] ... tag[N] 
filepkgcom[1] 


filepkgcom[N]) 


Each tag[...] is a flag recognized by the compiler (see Chapter 31) to control 
evaluation. The filepkgcom[...]’s are specifications for any of the commands in 
this Section that describe how those commands are to be treated when a file is 
compiled. 


17.2.19 Files 


A file is loaded using the function LOAD (see Section 17.9.1). When the file is 
loaded, its contents are evaluated as they are read and serve to initialize your 
INTERLISP environment. For large programs, you may have segmented the ap- 
plication into many files to make it more manageable for editing and printing. 
Manually specifying the loading of a large number of files becomes tedious and 
error-prone. INTERLISP provides a File Package command that allows you to 
specify the automatic loading of files from within a file. It takes the form 


(FILES file[1] ... file[2]) 


where “‘file’’ may be either a file or a list. If file[..] is an atom, it must be the 
name of a file, properly qualified, that is to be loaded. If it is a list, it must take 
the form 


(keyword[1] ... keyword[N]) 


Several keywords may appear in a single list. Keywords allow you to condi- 
tionally modify the loading process. The currently recognized keywords are 


FROM (directory) The file names appearing after the list 
are to be loaded from the specified 
directory. For example, 


(FILES (FROM LISPUSERS) MULTIFILEINDEX) 


SOURCE 


COMPILED 


LOAD 


LOADCOMP 
LOADFROM 
SYSLOAD 


PROP 


ALLPROP 
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The source version rather than the 
compiled version of the file will be 
loaded. 


The compiled version of the file will be 
loaded. This is the default keyword. 
Each implementation distinguishes its 
compiled versions from its source 
versions in a different manner. 
INTERLISP-10 appends the extension .COM 
to a file that is compiled. Thus, this 
keyword directs the LOAD to look for 
files having that extension. 


Load the file using the functions LOAD? 
(see Section 17.9.1). This keyword loads 
a file only it it has not previously 
been loaded. It is the default mode. 


Load the file using the function 
LOADCOMP? This keyword automatically 
implies SOURCE. 


Load the file using the function 
LOADFROM (see Section 17.9.4) rather 
than LOAD?. 


Set LDFLG to SYSOUT and load the 
specified files. This keyword is used 
mainly to load system files. 


Set LDFLG to PROP. This forces all 
function definitions to be stored under 
the EXPR property on property lists 
rather than being placed in function 
cells (see Chapter 8 for more detail). 


Set LDFLG to ALLPROP. Both function 
definitions and variable values will be 
stored on property lists rather than 
being stored in function cells or value 
cells, respectively. 


17.2.20 Variations on Command Structure 


The preceding sections have described a rigid format for each of the File Pack- 
age commands. In each case, the arguments associated with the command must 
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be explicitly coded within the command. However, we do not always know what 
is to be saved because this is a function of the dynamic environment. The File 
Package provides a method for determining what is to be done during the execu- 
tion of MAKEFILE. 

Each of the commands previously mentioned may be followed by the atom *. 
If so, the expression following the * is evaluated. Its value is used to determine 
the arguments to the command. For example, we might say 


(FNS makenode makeslot ...) 


to save functions of a program on the symbolic file. But, if we create functions 
during the session, we would like to have those saved on the file as well. To do so, 
we must be able to update the parameters of the commands as we create the 
functions. Thus, we can define an alternative form for the FNS command as 
follows: 


(FNS * <filename)FNS) 


where (filename) is the name of the file in which the function definitions are to 
be saved. 
We would define the command list as follows: 


(RPAQQ <filename)COMS 
((VARS <list of variables)) 
(FNS * <filename) FNS) ) ) 


(RPAQQ <filename)FNS 
(makenode makeslot ....)) 


If the expression following the * is an atom, its value must be a list that 
specifies the names of the functions whose definitions are to be saved. We say 
that the atom is a filevar. The name of the atom is composed of the file name 
concatenated with FNS. If the expression is a list, the list is evaluated to to pro- 
duce a list of function names. 

Each of the commands mentioned above may utilize this alternative form of 
argument specification for the command. Exceptions are made for the PROP 
and IFPROP commands where the * must follow the property name. For exam- 
ple, 


(PROP MACRO * «filename )MACROS) 


17.3 FILE PACKAGE FUNCTIONS 


This section describes the File Package functions that are used to manipulate 
files. The primary function that you need is to be able to make a file that is 
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composed of the various INTERLISP object definitions in your environment. 
Other functions include listing and compiling files, and determining where (on 
which noticed file) an object definition resides. 


17.3.1 Making Files 


Whenever you modify a file, you want to ensure that the changes are reflected in 
the permanent copy of the file that is stored on disk. The process of creating a 
new file on disk is known as making a file. MAKEFILE allows you to create a 
new version of the file at any time, even when the file does not yet exist. The 
format of MAKEFILE is 


Function: MAKEFILE 
# Arguments: 4 


Arguments: 1) a filename, FILENAME 
2) an options list, OPTIONS 
3) zero or more reprint functions, 
REPRINTFNS 
4) a source file, SOURCEFILE 


Value: The full file name (including version) of 
the new file. 


FILENAME is the name of the file to be created. A new version of the file 
will always be created, even if an existing version is specified as the value of 
FILENAME. If FILENAME has not previously been noticed, MAKEFILE no- 
tices the file. To make a file, there must be a corresponding File Package com- 
mand variable of the form <filename)COMS defined in your INTERLISP envi- 
ronment. MAKEFILE uses the commands found as the value of this variable to 
write the proper symbolic information to the file. In most cases, PRETTYDEF 
(see Section 17.8.1) will be used to place symbolic information in the file. 

OPTIONS is a list of arguments that direct the creation of the new file. The 
following options are available: 


FAST Forces PRETTYDEF to be invoked with 
PRETTYFLG set to NIL (see Section 17.8.1). 
The definitions of INTERLISP objects are 
printed rather than prettyprinted which 
results in a faster execution rate. 


RC Invokes RECOMPILE after PRETTYDEF to compile 
a new version of the file. 


C Invokes TCOMPL after PRETTYDEF. 
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CLISPIFY 


NOCLISP 


LIST 


REMAKE 


NEW 


In both cases, if the file has block 
definitions, BCOMPL or BRECOMPILE will be 
called to compile the file. 


These options may be followed by a single 
letter from the set {F, ST, STF, S} which 
provides direction to the compiler (see 
Section 31.1). 


Sets CLISPIFYPRETTYFLG to T while PRETTYDEF 
executes. Each function is CLISPIFYed before 
being prettyprinted (see Section 23.8). 


Sets PRETTYTRANFLG to T and calls PRETTYDEF. 
CLISP translations rather than CLISP 
expressions are printed on the file. This is 
useful if you are attempting to export the 
code to another LISP environment which does 
not support CLISP. 


Invokes LISTFILES on FILENAME (see Section 
17.3.4). 


Prettyprints only those functions that have 
been changed. Functions whose definitions 
are unchanged from previous versions of a 
file are merely copied from the earlier 
version. In many cases, this option will 
cause MAKEFILE to execute faster because 
most sessions make very few changes in a 
given file in a reasonably mature 
application. This is the default option for 
MAKEFILES as specified by a value of T for 
MAKEFILEREMAKEFLG. 


Forces a new version of the file to be 
created. That is, all functions are 
prettyprinted whether they have been changed 
or not. 


REPRINTENS and SOURCEFILE are used in remaking files as described 


in Section 17.3.2. 


Consider the following example: 


«(MAKEFILE 'SHK) 
{(KAISLER)SHK. .1 
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where SHKCOMS was previously initialized as 
((FNS * SHKFNS) (VARS * SHKVARS) ... other commands) 
You cannot make a file without a File Package commands variable, e.g., 


«(MAKEFILE 'shksys) 
SHKSYS not a file name 


If the file was loaded from a compiled version, certain information is not 
present in memory to create a new symbolic file. MAKEFILE displays the warn- 
ing message ““CAN’T DUMP; ONLY THE COMPILED FILE HAS BEEN 
LOADED”. This is because the noticed version of the file is the compiled code 
which does not contain the File Package commands to remake the file. 

If only the function definitions were loaded via LOADFNS or LOAD- 
FROM, MAKEFILE displays the warning message ‘“‘CAN’T DUMP: ONLY 
SOME OF ITS SYMBOLICS HAVE BEEN LOADED”. In either case, 
MAKEFILE seeks your approval to perform the dump anyway. If you decline, 
MAKEFILE returns the value ‘NOT DUMPED”. 


A Definition for MAKEFILE 

The following skeleton provides an example of the complexity of the File Pack- 
age functions. The function calls are merely the ‘‘tip of the iceberg”’ of a power- 
ful environmental control mechanism. 


(DEFINEQ 
(makefile (filename options reprintfns 
sourcefile) 
(PROG (file-type x file changes file- 
dates) 


(* 
Add filename to the list of 
noticed files. 


(addfile filename) 

(updatefiles) 

(* 
If OPTIONS is a single atom, 
make it a list; otherwise, do 
nothing. 

) 

(SETQ options (MKLIST options) ) 

(* 
Get the changes, if any, and the 
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current date of the file, if it 
exists. 


) 
(SETQ changes 
(GETPROP filename 
' FILECHANGES) ) 
(SETQ file-dates 
(LISTP (GETPROP filename 
'FILEDATES) ) ) 
(SETQ file-type (GETPROP filename 
'FILETYPE) ) 
loop0 
(COND 
((OR 
(MEMBER 'NEW options) 
(AND 3 
(NULL 
makefileremakeflg) 
(NOT 
(MEMBER 'REMAKE 
options) ))) 
(PRIN2 filename) 
(PRIN1 
(SELECTQ loadtype 
(COMPILED 
".-only the 


compiled file has 


been loaded'') 
(LOADFNS 
"--only some of 


it symbolics have 


been loaded'') 
(HELP) ) ) 
(COND 


( (NEQ 


(ASKUSER DWIMWAIT 
"shall I 
go ahead 
and dump 
anyway?" 


NIL T) 
'y) 
(GO out))) 
(SETQ sourcefile NIL) — 
(SETQ reprintfns NIL) ) 


n 


( (AND 
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((NULL file-dates) 
(* 
No FILE-DATES, so 
perhaps user made the 
COMS in memory. 
) 
(SETQ sourcefile T) 


(OR 
reprintfns 
(SETQ reprintfns 
changes) ) ) 
((EQUAL (filedate (CDAR file- 
dates) ) 


(CAAR file-dates) ) 

(* 
The previous version 
of the file is gone, 
so we must use the 
original and dump 
everything that has 
been changed. 


(SETQ sourcefile (CDAR 
file-dates) ) 
(OR 
reprintfns 
(SETQ reprintfns 
changes) ) ) 


(CDR file-dates) 
(EQUAL (filedate (CDADR file- 
dates) ) 

(CAADR file-dates) ) ) 
(* 


The previous version 
of the file has 
disappeared, so find 
the most recent 
version and dump all 
changes. 


) 

(SETQ sourcefile (CDADR file- 
dates) ) 

(SETQ changes 
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(SETQ reprintfns 
(UNION (CDR 2) 
(GETPROP 
filename 
'FILECHANGES ) 
)))) 
(T 


(PRIN1 "can't find either 
the previous version 
or the original 
version of") 

(SPACES 1) 

(PRIN2 filename) 

(PRIN1 ", so it will have 
to be written anew'') 

(SETQ sourcefile NIL) 

(SETQ reprintfns NIL) 

(SETQ options 

(CONS 'NEW options) ) 

(SETQ changes 

(GETPROP filename 
' FILECHANGES) ) 
(GO loop0) )) 
(AND 
(OR sourcefile reprintfns) 
(SELECTQ file-type 

(* 

File was originally 
loaded in compiled 
form, so do a LOADFROM 
to get declarations 


(COMPILED 
( LOADVARS 
'((DECLARE: -- DONTCOPY 
--)) 
(OR 
(CDAR file-dates) 
filename) ) ) 
(LOADFNS 
(* 
For REMAKE, not all 
variable definitions 
will have been loaded, 
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so we must obtain 
them. 


(LOADVARS T 
(OR (CDAR file- 
dates) 
filename) ) ) 
NIL)) 
(SETQ filename 
(PRETTYDEF NIL filename NIL 
reprintfns 
sourcefile 
changes) ) 
(SETQ lastfile NIL) 
(COND 
( (NOT 
(OR 
(EQMEMB 'DON'TLIST 
filetype) 
(MEMBER filename 
NOTLISTEDFILES) ) ) 
(SETQ NOTLISTEDFILES 
(CONS filename 
NOTLISTEDFILES) ) ) ) 
(COND 
( (AND 
(NOT 
(EQMEMB 'DON'TCOMPILE 
filetype) 
(INFILECOMS? T 'FNS (CAAR 
z)) 
(NOT 
(MEMBER filename 
NOTCOMPILEDFILES) ) ) 
(SETQ NOTCOMPILEDFILES 
(CONS filename 
NOTCOMPILEFILES) ) ) ) 
loop1 
(COND 
((NULL options) 
(RETURN filename) ) ) 
(SETQ x options) 
(SETQ options (CDR options) ) 
(SELECTQ (CAR x) 
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(RC 
(AND 
(MEMBER filename 
NOTCOMPILEDFILES) 
, (MAKEFILE1 filename T))) 
C 
(AND 
(MEMB filename 
NOTCOMPILEDFILES) 
(MAKEFILE1 filename) ) ) 
(LIST 
(AND 
(MEMBER filename 
NOTLISTEDFILES) 
(APPLY (FUNCTION LISTFILES) 
(LIST filename) ) )) 
(OR 
(MEMBER (CAR x) 
MAKEFILEOPTIONS) 
(RETURN 
(CONS (CAR x) 
'(— MAKEFILE 
CONFUSED) ) 
))) 
(GO loop1) 
out 
(RETURN 
(CONS filename 
; '(NOT DUMPED) ) )) 
)) 


17.3.2 Remaking Files 


Most symbolic files change slowly over time. That is, only a few of the function 
definitions change as a system is being developed. When symbolic files are large, 
considerable time may be consumed in creating a new version of the file. Time 
may be saved by rewriting only the definitions of those functions that have actu- 
ally been changed. This process is called remaking a file. MAKEFILE operates 
in this mode when REMAKE is specified as an option. 

You may tell MAKEFILE what is to be done. REPRINTENS, the third ar- 
gument to MAKEFILE, is a list of those functions that are to be explicitly pretty- 
printed on the new version of the file. SOURCEFILE, the fourth argument, 
specifies where the remaining definitions will be copied from. Typically, you will 
set both REPRINTFNS and SOURCEFILE to NIL whence MAKEFILE pretty- 
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prints those functions that have been changed since the last MAKEFILE or 
LOAD execution. 

When SOURCEFILE is NIL, MAKEFILE determines the most recent ver- 
sion from the FILEDATES property of FILENAME. It checks to see that that 
version still exists. If it does not, it attempts to locate the original version of the 
file that was used when the session was initiated. This allows a user, during a 
lengthy session, to create many versions of a file via MAKEFILE without fear of 
losing any information in the file. Rarely does a user delete a source file after 
loading, so the presumption of going back to the original file is a valid one. If 
MAKEFILE must return to the original file, it determines which files must be 
prettyprinted by taking the union of all the files from the FILECHANGES prop- 
erty with those contained in the original file. 

If MAKEFILE cannot find either the most recent version of the file or the 
original version, it displays the error message ““CAN’T FIND EITHER THE 
PREVIOUS VERSION OR THE ORIGINAL VERSION OF (filename), SO 
IT WILL HAVE TO BE WRITTEN ANEW”. In this case, all functions are 
prettyprinted. 

Because function definitions may be loaded from files in several different 
ways (see Section 17.9), MAKEFILE must be cognizant of how these definitions 
were loaded. If the file was loaded from a compiled version, MAKEFILE must 
reload the declarations in order to write the new symbolic file. If only functions 
were loaded via LOADFNS, then MAKEFILE executes LOADVARS to obtain 
the variables as well. 


17.3.3 Making Multiple Files 
MAKEFILES allows you to process several files at once. MAKEFILES takes the 


form 
Function: MAKEFILES 
# Arguments: 2 
Arguments: 1) an option list, OPTIONS 
2) a list of files, FILES 
Value: A list of all files that are made. 


For each file on FILES, MAKEFILES invokes MAKEFILE with OP- 
TIONS. That is, it performs 


(MAKEFILE (CAR files) options NIL NIL) 


If FILES is NIL, then MAKEFILES uses FILELST. If any typed definitions 
have been defined or changed that do not appear on any of the files in FILELST, 
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MAKEFILES asks you, via ADDTOFILES?, about which files these definitions 
should go to. 
MAKEFILES returns a list of all the files that it has made. 


A Definition for MAKEFILES 
We might define MAKEFILES as follows: 


(DEFINEQ 
(makefiles (options files) 
(PROG (temporary) 
(* 


First, ensure that all updates are 
posted the proper files. 


) 
(updatefiles) 
(COND 
((NULL files) 
(* 
If there is a File Package 
type object that has been 
defined, but which has not 
been assigned to a file, 
ADDTOFILES? is invoked to ask 
you where to put the object. 
) 
(MAPC FILEPKGTYPES 
(FUNCTION no-resident-file) ) 
(AND temporary (addtofiles?) ))) 


(ATOM options) 
options 
(SETQ options (LIST options) )) 


((NULL files) 
(x 


If FILES is null, 
use FILELST. 


FILELST) 
((ATOM files) 
(LIST files) ) 
(T files) ) 
(FUNCTION make-each-file) ))) 


)) 


——— 
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The function NO-RESIDENT-FILE determines if a File Package type has 
been defined that is not present in any file of FILES. It will cause the printing of 
a warning message to the user. 


(DEFINEQ 
(no-resident-file (type) 
(AND 
(FILES?1 type 
(COND 
((NULL temporary) 
"Note: The following 
are not contained on 
any file:'')) 
(T (SPACES 4)))) 
(SETQ temporary T)) 
)) 


MAKE-EACH-FILE determines if the name passed to it is really that of a 
file. If so, it invokes MAKEFILE with that name; otherwise, it merely returns 
NIL. 


(DEFINEQ 
(make-each-file (filename) 
(PROG (property) 
(COND 
((OR 
(NLISTP 
(SETQ property 
(GETPROP filename 
'FILE) )) 
(NULL (CDR property) ) ) 
(RETURN NIL))) 
(PRIN2 filename) 
(PRIN1 '...) 
(RETURN 
(PROGL 
(LIST (makefile filename 
options) ) 
(TERPRI) ))) 
)) 


17.3.4 Listing Files 
LISTFILES displays the contents of files. It takes the following form 
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Function: LISTFILES 

# Arguments: 1 

Argument: 1) A list of files to be displayed, FILES 
Value: NIL. 


LISTFILES is an NLAMBDA, nospread function. 

If FILES is NIL (the normal case), the File Package variable NOTLISTED- 
FILES is used. The purpose of this function is to see the files which have been 
changed since the last MAKEFILE. As each file name is printed, it is removed 
from NOTLISTEDFILES. If a file is not found, LISTFILES displays the warn- 
ing “‘<filename) NOT FOUND” and proceeds. 

Consider the following example: 


<-(LISTFILES complex) 
file <«KAISLER)COMPLEX..1 sent to the penguin 
NIL 


The IRM notes that the implementation of LISTFILES depends on the un- 
derlying operating system. INTERLISP-10 uses the printing utility of the 
TENEX operating system, while INTERLISP-D uses the EMPRESS utility. 


17.3.5 Compiling Files 


COMPILEFILES executes the RC option of MAKEFILE for each member of its 
argument, FILES. It takes the form 


Function: COMPILEFILES 

# Arguments: 1-N 

Arguments: -1-N) a list of filenames, FILE[1] ... 
FILE[N] 

Value: NIL. 


COMPILEFILES is an NLAMBDA, nospread function. 

If FILES is NIL, NOTCOMPILEDFILES is used. The purpose of this func- 
tion is to allow a user to make changes in a number of files and then recompile 
them all at once. When multiple files are used in a program and changes have to 
be made in several files, this provides a convenient method for ensuring recompi- 
lation of all the necessary files. 

Consider the following example: 


<-(COMPILEFILES complex) 
compiling COMPLEX 
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COMPLEX.COM not found, shall I TCOMPL <(KAISLER)COMPLEX. .1 
instead? ... Yes 


listing? ...File only 
(COMPLEX (R I) NIL) 

(REAL (CX) NIL) 

(IMAG (CX) NIL) 

(CPLUS (CX1 CX2) NIL) 
(CDIFFERENCE (CX1 CX2) NIL) 
(CZERO NIL NIL) 

(CMULT (CX1 CX2) NIL) 
(PRINT.COMPLEX (CX1) NIL) 
NIL 


«-(COMPILEFILES test) 
compiling TEST 

FILE NOT FOUND 

TEST 

(OPENF broken) 


If COMPILEFILES cannot open the specified file, it forces an error and 
enters the Break Package (see Chapter 20). 


17.3.6 Cleaning Up Files 


CLEANUP is a general workhorse that performs a MAKEFILE, LISTFILES, 
and COMPILEFILES for any files that appear on its argument, FILES. It takes 
the form 


Function: CLEANUP 

# Arguments: 1-N 

Arguments: 1-N) a list of filenames, FILE[1] ... 
FILE[N] 

Value: NIL. 


CLEANUP is an NLAMBDA, nospread function. 

If FILES is NIL, FILELST is used. It returns a value of NIL. CLEANUP is 
driven by its own options list, CLEANUPOPTIONS. Initially, this variable has 
as its value (LIST RC). You may change the value to direct its execution. 

If a file is not loaded, CLEANUP does nothing. For example, 


«(CLEANUP complex) 
NIL 
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«(LOAD 'COMPLEX) 

«KAISLER) COMPLEX. .1 

FILE CREATED 28-Jul-84 10:48:03 
COMPLEXCOMS 


(CLEANUP complex) 
COMPLEX...file <KAISLER)COMPLEX..2 sent to the penguin 


compiling <KAISLER)COMPLEX. .2 


COMPLEX.COM not found, shall I compile 
«KAISLER)COMPLEX..2 instead? ... Yes 
(COMPLEX (R I) NIL) 

(REAL (CX) NIL) 

(IMAG (CX) NIL) 

(CPLUS (CX1 CX2) NIL) 

(CDIFFERENCE (CX1 CX2) NIL) 

(CZERO NIL NIL) 

(CMULT (CX1 CX2) NIL) 

(PRINT.COMPLEX (CX1) NIL) 

NIL 


17.3.7 Determining File Status 


After you have been working on a program for awhile, you may want to deter- 
mine the status of the files that you have been working with. FILES? displays on 
the terminal the names of those files that 


Have been modified, but not dumped 

Dumped, but not listed 

Dumped, but not compiled 

The names of any functions and types that have been defined but are not 
contained in any file. 


It takes the following form 


Function: FILES? 

# Arguments: 0 

Arguments: N/A 

Value: A list of functions and variables which 


have not been assigned to files and a list 
of files that have not been made (see 
example below). 
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If there are any functions or types that have not been assigned to files, 
FILES? invokes ADDTOFILES? to allow you to specify where these functions 
and types are to be assigned. 

Consider the following example: 


«(RECORD test (a b c d e)) 
TEST 


<-(DEFINEQ (ADD3 (a b c) (IPLUS a b c))) 
(ADD3) 


<— (FILES?) 

the records: TEST...to be dumped 

the functions: ADD3...to be dumped 
want to say where the above go? ... No 
NIL 


INTERLISP queries you about where the files should go via ASKUSER. If 
you fail to respond within the specified period, it automatically assumes NIL and 
exits. 


A Definition for FILES? 
We might define FILES? as follows: 


(DEFINEQ 
(files? NIL 
(* 
Make sure all updates are posted to the 
files. 


(updatefiles) 
(PROG (files temporary) 
(SETQ files 
(MAPCONC filelst 
(FUNCTION files-1?))) 


(COND 
(files 

(* 
If there are any files that 
have been changed, notify 
the user of the action to 
be performed for each file. 

) 


(MAPRINT files T NIL 
"... to be dumped." 
', NIL T))) 
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(* 
Inspect all objects to see if there 
are any which have not been assigned 
to files. 


(MAPC FILEPKGTYPES (FUNCTION files-2?) ) 
(AND temporary (ADDTOFILES?) ) 
( AND 
(SETQ files NOTLISTEDFILES) 
(MAPRINT files T NIL 
",.. to be listed." 
', NIL T)) 
(AND 
(SETQ files NOTCOMPILEDFILES) 
(MAPRINT files T NIL 
",.. to be compiled." 
', NIL T)) 
(RETURN) ) 


FILES-1? and FILES-2? are utility functions defined as follows: 


(DEFINEQ 
(files-1? (x): 
(AND 
(CDR (GETPROP x 'FILE)) 
(LIST x)) 
)) 


(DEFINEQ 
(files-2? (type) 
(AND 
(files?1 type (AND files "' plus") ) 
(AND (NULL files) | 
".,. to be dumped.'))) 

(SETQ temporary T)) 

)) 


FILES?1 handles the printing chores for examining FILEPKGTYPES. It 
may be defined as 


(DEFINEQ 
(files?1 (type x y) 
(PROG (a-string a-list) 
(COND 


——— 
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( (NOT 
(AND 
(LITATOM type) 
(SETQ a-string 
(fetch DESCRIPTION of type) ) 
(LISTP 
(SETQ a-list 
(fetch CHANGED of 
type) )))) 
(RETURN NIL))) 
(AND x (PRIN1 x T)) 
(PRIN1 "the " T) 
(PRIN1 a-string T) 
(COND 
(NIL 
( IGREATERP (LENGTH a-list) 6) 
(PRIN1 "' on" T) 
(PRIN2 (CAR type) T)) 
(T 
(MAPRINT a-list T'"': " 
NIL. *, 
(FUNCTION files?1-indent) ))) 
(AND y (PRIN1 y T)) 
(TERPRI T) 
(RETURN T)) 
)) 


where FILES?1-INDENT is defined as 


(DEFINEQ 
(files?1-indent (x) 
(COND 
( (NOT 
(ILESSP (IPLUS (POSITION T) 
(NCHARS x T T) 
3) 
(LINELENGTH) ) ) 
(TERPRI) 
(SPACES 8))) 
(PRIN2 x) 


)) 


17.3.8 WHEREIS: Finding Types in Files 


WHEREIS allows you to locate an instance of a file package type in a list of files 
that you specify. WHEREIS has the following format 
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Function: WHEREIS 
# Arguments: 3 


Arguments: 1) the name of an object, NAME 
2) the type of the object, TYPE 
3) A list of files, FILES 


Value: A list of all files that contain NAME as a 
TYPE. 


WHEREIS looks at all the files in FILES to see if the object NAME is in- 
cluded in the file with specified TYPE. If TYPE is NIL, WHEREIS assumes the 
type to be FNS, i.e., looking for a function list. If FILES is NIL, FILELST is 
used. Since FILELST is a list of all files ‘‘noticed”’ by the user as a result of 
loading or making files, the search may require considerable amounts of time. 

Consider the following examples: 


«-(WHEREIS 'CMULT) - 
(COMPLEX) 


“(WHEREIS 'JUNK) 
NIL 


«(WHEREIS 'CREATE.NODE 'FNS) 
(FRAME) 


If an object of the specified type cannot be located in any of the specified 
files, WHEREIS returns NIL. 


17.3.9 Marking Changes in a File 


Whenever a function is defined or modified, MARKASCHANGED is invoked to 

keep track of the change. This works as well for records and other file package 

types. Its purpose is to keep a consistent record of all modifications to a file so 

that the file may be written properly at the end of a session. The object is to 

ensure that you never lose work that you have performed during the session. 
The format of MARKASCHANGED is 


Function: MARKASCHANGED 


# Arguments: 3 


Arguments: 1) the name of an object, NAME 
2) the type of the object, TYPE 
3) a reason for the change, REASON 


Value: The name of the object. 
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MARKASCHANGED marks NAME of type TYPE as being changed. 
REASON is a literal atom that specifies how the object was changed. Currently, 
MARKASCHANGED recognizes the following values: 


DEFINED An object of type TYPE called NAME 
has been defined in your virtual 
memory. 


CHANGED An object of type TYPE called NAME 
has been modified via the Editor. 


DELETED An object of type TYPE called NAME 
has been deleted by DELDEF. 


CLISP An object of type TYPE called NAME 
has been modified by a CLISP 
translation. 


T is interpreted in the same way as DEFINED, while NIL is interpreted as 
CHANGED. Earlier versions of INTERLISP did not accept reasons, but merely 
noted whether the object was defined or changed. 

Changes to objects are recorded in the Masterscope (see Chapter 26) data- 
base. 

Consider the following example: 


«<(MARKASCHANGED 'ADD3 'FNS 'CHANGED) 

ADD3 

You may call MARKASCHANGED directly to record changes to objects. 
Generally, however, you will use MARKASCHANGED to record changes for 
user-defined datatypes. 

A corresponding function, UNMARKASCHANGED, allows you to undo 
the effects ofp MARKASCHANGED. It takes the form 


Function: UNMARKASCHANGED 

# Arguments: 2 

Arguments: 1) the name of an object, NAME 
2) the type of the object, TYPE 

Value: The name of the object if it was marked as 
changed and is now unmarked; otherwise, 
NIL. 


UNMARKASCHANGED erases the entry in the Masterscope database that 
marked the object NAME of type TYPE. If no NAME of type TYPE was 
marked, UNMARKASCHANGED returns NIL, otherwise NAME. 
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(UNMARKASCHANGED 'ADD3 'FNS) 
ADD3 


17.3.10 Determining What has been Changed 


After you have made many changes to a file or have not modified a file for a long 
period of time, it is useful to find out what changes have been made. The File 
Package function FILEPKGCHANGES prints the contents of the ‘‘changes to:”’ 
section of the file header. It takes the following form: 


Function: FILEPKGCHANGES 

# Arguments: 2 

Arguments: 1) a File Package type, TYPE 
2) a list of objects, LST 

Value: A list of objects that have been marked as 
changed. 


FILEPKGCHANGES is a LAMBDA, nospread function. 

It examines all objects that have been changed (i.e., marked) but which 
have not yet been associated with their corresponding files. If LST is specified, 
the value of FILEPKGCHANGES is assigned as the value of that list. 
FILEPKGCHANGES returns a list of all objects marked as changed as a list of 
the form (typename . changedobjects). 


« (FILEPKGCHANGES ) ‘ 
((RECORDS TEST) (VARS X) (FNS ADD3)) 


<—(FILEKGCHANGES 'FNS) 
(ADD3) 


17.3.11 Adding to Files 


ADDTOFILES? is a general housekeeping function. After performing a 

MAKEFILES, CLEANUP, OR FILES?, there may remain objects that are, as 

yet, unassociated with files. Often, this happens during a particularly productive 

programming session. In order to ensure that all these changes and creations are 

saved, you have to identify what files they are associated with. 
ADDTOFILES? takes the following form: 


Function: ADDTOFILES? 

# Arguments: 0 

Arguments: N/A 

Value: NIL, but has side effects (see below). 
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ADDTOFILES? asks you about the various changed, but unassociated, 
items, concerning what files they should belong to. You may give one of seven 
responses to each question (which is actually the name of an object): 


1. A file name or the name of a list, such as SHOWGRAPH or SHOW- 
GRAPHCOMS, whence the File Package uses ADDTOFILE to add the 
item to the corresponding file or list. 

2. A <line-feed) indicating that the previous response should be used 
again. 

3. A <space) or <carriage-return) indicating that no action should be 
taken for this item. 

4. A | (<right-square-bracket)) that indicates that the item is a dummy. 
The item is added to NILCOMS in the file. 

5. A [ (<left-square-bracket)) which indicates that the definition of the 
item is to be prettyprinted to the terminal and the question reasked. If 
you had forgotten about the value of the item, this allows you to review it 
before deciding where it should go. 

6. A( whence you are prompted with ‘““LISTNAME: (“‘. You must enter the 
name of a File Package command list. If such a list is found in the 
-COMS definition of the file, then the item and its definition will be 
added to the appropriate list. Otherwise, an error message will be 
printed and you will be reprompted. 

7. An @ (<at-sign)) whence you are prompted with “NEAR: (’”’. You must 
type in the name of another object. The specified item is inserted into the 
command list associated with that object. Thus, if you don’t want to in- 
spect the definition of an item but know that it is similar to one previously 
associated, you may simply direct the File Package to place it with the 
former item. 


Consider the following example (assuming some unassociated objects): 


<— (ADDTOFILES? ) 
want to say where the above go? Yes 
(variables) 
X Nowhere "because I typed ]" 
(records) 
TEST File Name: COMPLEX 
(functions) 
ADD3 (DEFINEQ "because I typed [" 
(ADD3 
(LAMBDA (A B C) **COMMENT** 
(IPLUS A B C)))) 

ADD3 List: (TESTCOMS 

new list? Yes 
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put list TESTCOMS on file: 
(NIL) 


“—testcoms 
( ADD3) 


17.4 DEFINING NEW FILE PACKAGE TYPES 


The previous section described a set of functions for manipulating the defini- 
tions of objects in a file regardless of their type. However, INTERLISP allows 
you to manipulate individual objects within a file. To manipulate new objects, 
you merely define how they are treated by the type-independent functions de- 
scribed in the following section. 


17.4.1 FILEPKGTYPE 


FILEPKGTYPE allows you to create new file package types. You will use it pri- 
marily to define commands that store user-defined data structures on a file. It 
takes the form 


Function: FILEPKGTYPE 
# Arguments: 1-N 


Arguments: 1) a type name, TYPE 
2) a property, PROP 
3) a value, VALUE 
4-N) property and value pairs 


Value: The type name. 


FILEPKGTYPE is a LAMBDA, nospread function. 
TYPE is the name of the new file package type. PROP and VALUE have the 
meanings described below: 


GETDEF Defines a function that, is used to 
retrieve the definition of an object 
from the file. GETDEF (see Section 
17.5.1) uses this function. It takes 
three arguments: NAME, TYPE, and 
OPTIONS. 


PUTDEF Defines a function that is used to 
store the definition of an object on 
a file. PUTDEF (see Section 17.5.2) 
uses this function. It takes three 
arguments: NAME, TYPE, and 
DEFINITION. 
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DELDEF Defines a function that is used to 
remove the definition of an object 
from a file. DELDEF (see Section 
17.5.4) uses this function. It takes 
two arguments: NAME and TYPE. 


NEWCOM Defines a function that specifies how 
to make a file package command to 
dump an object of a given type. This 
function is used by ADDTOFILE and 
SHOWDEF. It takes four arguments: 
NAME, TYPE, LISTNAME, and FILE. 


If this property is not specified, 
DEFAULTMAKENEWCOM is called to 
construct an expression of the form 


(<type) * <filevar)) 


where (filevar) either has the value 
of LISTNAME, if non-NIL, or the value 
of (FILECOMS <file)). 


WHENCHANGED Its value is a list of functions to 
be applied when an object NAME of 
TYPE is changed or defined. Each 
function takes three arguments: NAME, 
TYPE, and NEWFLG. 


(FILEPKGTYPE 'I.S.OPRS 
"DESCRIPTION "iterative statement 
operators" 
'WHENCHANGED '(CLEARCLISPARRAY) ) 


WHENFILED Its value is a list of functions to 
be applied to an object NAME of TYPE 
when it is added to a file. Each 
function takes three arguments: NAME, 
TYPE, and FILE. 


WHENUNFILED Its value is a list of functions to 
be applied to an object NAME of TYPE 
when NAME is removed from a file. 
Each function takes three arguments: 
NAME, TYPE, and FILE. 


DESCRIPTION Its value is a string that describes 
what instances of this type are. 
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(FILEPKGTYPE 'USERMACROS 
"DESCRIPTION "edit macros'') 


Where VALUE defines a function, the function may be defined as 
LAMBDA or NLAMBDA expression, as a FUNCTION expression, or as a list 
with the file name as its sole element. 

You may determine the current value of a property by executing the expres- 
sion: 


(FILEPKGTYPE (type) <property) ) 


You may determine the defined properties for a given type using the expres- 
sion: 


(FILEPKGTYPE <type)) 
Consider the following example: 


<-(FILEPKGTYPE 'FNS) 
(DESCRIPTION "functions"') 


«-(FILEPKGTYPE 'ALISTS) 
(DESCRIPTION "alist entries'' WHENCHANGED 
(ALISTS . WHENCHANGED) ) 


17.4.2 File Package Type Definitions 


In this section, we give a few examples from the File Package to demonstrate 
how it uses the command FILEPKGTYPE to define some of the file package 
types that are described in Section 17.2. 


(FILEPKGTYPE 'PROPS 
"DESCRIPTION "property lists" 
'WHENCHANGED (FUNCTION PROPS.WHENCHANGED) ) 


where PROPS.WHENCHANGED might be defined as follows 


(DEFINEQ 
(props.whenchanged (name type reason) 
(PROG (property-type) 
(SETQ property-type 
(GETPROP (CADR name) ' PROPTYPE) ) 
(COND 
(property-type 
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(MARKASCHANGED (CAR name) 
property-type 
reason) ) 
(T 
(SELECTQ (CADR name) 
(CLISPWORD 
(CLEARCLISPARRAY (CAR name) )) 
NIL) ))) 
)) 


(FILEPKGTYPE 'EXPRESSIONS 
"DESCRIPTION "expressions"! 
"WHENCHANGED (FUNCTION 
EXPRESSIONS . WHENCHANGED ) 
'EDITDEF (FUNCTION NILL) ) 


where EXPRESSIONS.WHENCHANGED might be defined as follows 


(DEFINEQ 
(expressions.whenchanged (expression) 
(SELECTQ (CAR expression) 
((SETQ SETQQ) 
(UNMARKASCHANGED (CADR expression) 
'VARS) ) 
((PROGN PROG) 
(MAPC (CDR expression) 


(FUNCTION 
(LAMBDA (x) 
(EXPRESSIONS.WHENCHANGED x) )))) 
(ADVISE 
(AND 


(EQUAL (CAADR expression) 
(QUOTE QUOTE) ) 
(MAPC (PACK-IN (CADR (CADR expression) )) 
( FUNCTION 
(LAMBDA (fn) 
(UNMARKASCHANGED fn 
"ADVICE) ))))) 
NIL) ) 


)) 


17.5 MANIPULATING FILE PACKAGE TYPES 


As we have seen, the File Package provides a powerful and flexible environment 
for managing your applications. The structure of a file created using the File 
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Package may become very complex if you take advantage of all the facilities pro- 
vided by it. Consequently, the File Package inlcudes many functions to manage 
the type definitions that describe the environemnt and processing of a file. 


Conventions 


The File Package functions observe several conventions concerning the nature 
and processing of arguments: 


1. When an (atom) is given where a list is expected, the functions convert 
the argument to (LIST <atom)). This allows processing to proceed with- 
out causing errors on trivial mistakes (one interpretation) and makes the 
File Package rather user-friendly (second interpretation). | 


2. Singular forms of file package types are also recognized, e.g., 


VAR 


RECORD 


COM 


FILE 


VARS ° 
RECORDS 
COMS 
FILES 


3. If TYPE (see below) has the value NIL, a default of FNS is assumed. 


4. If FILES (see below) has the value NIL, the function uses the value of 
FILELST (a list of all noticed files) instead. 


5. The location of the definition, SOURCE, will be interpreted as follows: 


? 


CURRENT 
SAVED 


FILE 


«file) 


NIL 


Use the definition determined by: 


a. that currently in effect 
b. a saved definition 


ec. a definition read from a file that is 
identified by WHEREIS (see Section 17.3.8) 
in that order. 


Use the definition currently in effect. . 


Use the saved definition (i.e., one that was 
stored by SAVEDEF). 


Use the definition found in the first file 
that is identified by WHEREIS. 


Use the definition, if any, that may be 
found in the specified file. <file>) may be a 
list of files which are searched in order of 
occurrence in the list. 


Equivalent to ?. 
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Note that NIL subsumes the values CURRENT, SAVED, and FILE 
in the order indicated. These alternatives exist to allow you to force a 
specific instance of a definition. ; 
6. All functions that make destructive changes to the contents of the file are 
undoable. 


17.5.1 Getting a Type Definition 


You may obtain the definition of an item associated with a particular type using 
GETDEF, which takes the format 


Function: GETDEF 
# Arguments: 4 


Arguments: 1) an item, NAME 
2) a type idntifier, TYPE 
3) the location of the definition, SOURCE 
4) an option list, OPTIONS 


Value: An S-expression that is the definition of 
the item. 


GETDEF reads an S-expression from SOURCE for NAME of the given 
TYPE. There are several cases: 


FNS 
If TYPE is FNS, GETDEF returns a LAMBDA/NLAMBDA expression, e.g., 


<(OPENFILE 'AMISMAP 'INPUT 'OLD) 
[DSK] AMISMAP!5 


<-(GETDEF 'POINT.SUM 'FNS) 
(LAMBDA (point1 point2) 
(point.new 
(PLUS 
(fetch XCOORD of point1) 
(fetch XCOORD of point2)) 
(PLUS 
(fetch YCOORD of point1) 
(fetch YCOORD of point2)))) 


where with SOURCE = NIL and no current saved definition, WHEREIS has 
identified AMISMAP as the source of the definition. AMISMAP was noticed 
when it was opened. 

Alternately, we can just get the arguments list via 
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+(GETDEF 'POINT.SUM 'FNS 'AMISMAP '(FAST ARGLIST) ) 
(LAMBDA (point1 point2) ) 


VARS 
If TYPE is VARS, GETDEF returns the value of NAME, e.g., 


*«-(GETDEF 'RADIANS.PER.DEGREE 'VARS) 
-01745328 


RECORDS 
If TYPE is RECORDS, GETDFEF returns the structure of the record, e.g., 


«-(GETDEF 'RECTANGLE 'RECORDS) 
(RECORD RCETANGLE (ORIGIN . CORNER) ) 


FIELDS 
If TYPE is FIELDS, GETDEF returns a list of all record declarations that con- 
tain NAME as a field, e.g., 


«-(GETDEF 'ORIGIN 'FIELDS) 
(RECORD RECTANGLE (ORIGIN . CORNER) ) 


FILES 
If TYPE is FILES, GETDEF returns the command list for the file whose name is 


the value of NAME, e.g., 


+(GETDEF 'AMISMAP 'FILES) 
(((FNS * AMISMAPFNS) 
(VARS * AMISMAPVARS) 
(RECORDS RECTANGLE) 
(CONSTANTS (PI 3.15159)) 
(INITVARS 
(RADIANS. PER. DEGREE 
(QUOTIENT PI 180.0)) 


eee 
(("3-NOV-83 05:17:38"' . [DSK]AMISMAP. ;1)) 
)) 


Other Types 
For all other types, GETDEF returns the S-expression that would be printed if 


NAME were dumped to the file as TYPE, e.g., 


(GETDEF 'EDITHIST 'SPECVARS 'DEDIT) 
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Otherwise ‘ 
Otherwise, if GETDEF cannot find a definition for NAME, an error is caused, 
e.g., 


«-(GETDEF 'POINT.MULTIPLY) 
POINT .MULTIPLY 
(FNS definition not found) 


OPTIONS is an atom or a list of atoms that direct the function to adhere to 
certain restrictions. These include: 


NOCOPY Does not return a new copy of the 
definition. 

NODWIM Does not DWIMIFY (see Section 22.5) the 
definition. 

NOERROR Returns NIL if no definition is found. 

«string) If OPTIONS is or contains a string, it is 
returned when a definition for a name is 
not found. 


17.5.2 Creating a Definition 
You may create a definition for an item according to a given file package type 
using PUTDEF, which takes the form 

Function: PUTDEF 

# Arguments: 3 


Arguments: 1) an item, NAME 
2) a type identifier, TYPE 
3) a definition, DEFINITION 


Value: NAME, if successful. 


PUTDEF associates DEFINITION with NAME according to TYPE. There 
are several cases: 


FNS 
If TYPE is FNS, PUTDEF executes a DEFINE, i.e., 


<(PUTDEF 'POINT.SUM 
'FNS 
"(LAMBDA (pointi point2) 
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(point.new 
(PLUS point1l:xcoord point2:xcoord) 
(PLUS point1:ycoord 
point2:ycoord) ))) 
POINT .SUM 


<_ 
is equivalent to (DEFINE ' poirit.sum ...). 


VARS 
If TYPE is VARS, PUTDEF executes a SAVESET (see Section 25.4.1), i.e., 


«-(PUTDEF 'x 'VARS (LIST 'a 'b 'c)) 
X 


is equivalent to 


«-(SAVESET 'x (LIST 'a 'b 'c) T) 
(A B C) 


Note that using SAVESET makes the PUTDEF operation undoable (see 
Section 25.4). 


FILES 
If TYPE is FILES, PUTDEF establishes a command list (e.g., -COMS expres- 
sion) and notices the file. For example, 


«-(PUTDEF 'TEST 

"FILES 

(LIST (LIST 'FNS '* 'TESTFNS) )) 
TEST 


<-FILELST 
(TEST) 


<-TESTCOMS 
((FNS * TESTFNS) ) 


ADVISE 

If TYPE is ADVISE, PUTDEF will put DEFINITION under the property 
READVICE on NAME’s property list and invoke READVISE to advise the item 
(see Section 21.3). 


17.5.3 Copying Definitions 


You may copy a definition from one item to another via COPYDEF, which takes 
the format 
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Function: COPYDEF 
# Arguments: 5 


Arguments: 1) the source atom, OLD 
2) the destination atom, NEW 
3) a type identifier, TYPE 
4) the location of the definition, SOURCE 
5) a list of options, OPTIONS 


Value: The name of the new object. 


COPYDEF copies the appropriate definition from OLD to NEW. COPY- 
DEF is usually used to produce a new copy of a file. When TYPE is FILES, 
COPYDEF performs the following operations: 


1. Establishes the command list for the file (NEW)COMS. 

2. Notices NEW. 

3. Modifies the individual -COMS expressions such as VARS and FNS 
(e.g., (OLD) VARS becomes (NEW) VARS). 

4. Invokes MAKEFILE to create the new file. 


Consider the following example: 


“-(COPYDEF 'TEST 'GOOD 'FILES) 
GOOD 


<- FILELST 
(GOOD TEST) 


<GOODCOMS 
((FNS ¥ GOODFNS) ) 


Applying COPYDEF to a function definition, we obtain: 


«-(COPYDEF 'SIGN 'LSEQGTO 'FNS 'COMPLEX) 
LSEQGTO 


«(PP LSEQGTO) 
(LSEQGTO 
(LAMBDA (X) 
(COND 
((GREATERP x 0.0) 1) 
((LESSP x 0.0) -1) 
(T 0)))) 
(LSEQGTO) 


596 _—s— The File Package 


17.5.4 Deleting a Definition 


You may delete the definition associated with an atom via DELDEF, which 
takes the format 


Function: DELDEF 
# Arguments: 2 
Arguments: 1) an item, NAME 
2) a type identifier, TYPE 
Value: NAME, if successful. 


DELDEF removes the definition of TYPE associated with NAME that is 
currently in effect. Consider the following example: 


<(DELDEF 'LSEQGTO 'FNS) 
LSEQGTO 


«(PP LSEQGTO) 
(LSEQGTO not printable) 
(LSEQGTO) 


because the contents of the function definition cell have been erased. 
<(SETQ x (LIST 'reagan 'bush 'mondale 'ferraro) ) 


(reagan bush mondale ferraro) 


«-(DELDEF 'x 'VARS) 
X 


-x 
UNBOUND ATOM 
X 


17.5.5 Showing Definitions 
You may want to see how a definition would appear when it is written to a file. 
SHOWDEF prettyprints the definition for you. It takes the format 
Function: SHOWDEF 
# Arguments: 3 


Arguments: 1) an item, NAME 
2) a type identifier, TYPE 
3) a file name, FILE 


Value: The prettyprinted form of the definition. 
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SHOWDEF is used by several File Package functions when they do not 
know where to place a function. If you do not tell them, these functions show you 
the definition and re-ask you where to place it. It is primarly used by ADDTO- 
FILES? (see Section 17.3.11). 

Consider the following example: 


*-(SHOWDEF 'CZERO 'FNS) 
(DEFINEQ 
(CZERO 
(LAMBDA NIL 
(COMPLEX 0.0 0.0)))) 
T 


17.5.6 Editing a Definition 


EDITDEF allows you to edit the definition of an item of a given type. It takes the 
form 


Function: EDITDEF 
# Arguments: 4 


Arguments: 1) an item, NAME 
2) a type identifier, TYPE 
3) the location of the definition, SOURCE 
4) an optional list of editor commands, 
COMMANDS 


Value: The name of the object. 
EDITDEF is equivalent to: 


Using GETDEF to obtain the definition form SOURCE. 
Applying the editing commands via EDITE to the definition. 
Using PUTDEF to replace the definition at SOURCE. 


EDITDFEF is particularly convenient because you do not have to load the file 
contents (if the definition resides on an noticed file) in order to edit the defini- 
tion. Moreover, no memory is consumed because the function is only loaded 
within the editor environment. 

If SOURCE is NIL, EDITDEF uses the definition of the object in memory. 


«-(EDITDEF 'SLOTRECORD 'RECORD NIL '(R ID IDENTIFIER) ) 
SLOTRECORD 


«-(RECLOOK 'SLOTRECORD) 
(RECORD SLOTRECORD 
(IDENTIFIER VALUE TYPE RELATION OFFSPRING) ) 
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If COMMANDS is NIL, EDITDEF places you in the Editor where it waits 
to receive commands that you type in. See Chapter 19 for a discussion of the 
Editor. 


17.5.7 Saving and Unsaving Definitions 


You may save the definition of an item for later retrieval. You may either provide 
a definition as an argument or use the definition currently in effect. SAVEDEF 
takes the form 


Function: SAVEDEF 
# Arguments: 3 


Arguments: 1) an item, NAME 
2) a type identifier, TYPE 
3) a definition, DEFINITION 


Value: The name of the property under which the 
definition is saved. 


SAVEDEF takes either DEF or the current definition in effect, if DEFINI- 
TION is NIL, and stores it such that it may later be retrieved by either GETDEF 


or UNSAVEDEF. 
If TYPE is FNS or NIL (whence FNS is assumed), SAVEDEF stores the 


definition on the item’s property list under the property EXPR, CODE, or 
SUBR depending on whether source or compiled format, e.g., 


<-SAVEDEF 'SIGN 'FNS) 
EXPR 


<(GETPROPLIST 'SIGN) 
(EXPR (LAMBDA (X) (COND ((GREATERP X 0.0) 1) ((LESSP X 
0.0) -1) (T 0)))) 


If TYPE is VARS, the definition is stored on the property list under the 
property VALUE. Otherwise, it is saved in an internal data structure, SAVED- 
DEFS, e.g., 


«-(SAVEDEF 'COMPLEX 'RECORD) 
RECORDS 


<-SAVEDDEFS 
((RECORDS (COMPLEX DATATYPE COMPLEX ((REAL FLOATP) (IMAG 


FLOATP) ) ))) 


UNSAVEDEF is the corresponding function that allows you to unsave defi- 
nitions that you have saved in the past. When you unsave a definition, the defini- 
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tion found on the property list or the internal data structure becomes the defini- 
tion currently in effect for the item (i.e., it replaces the current definition in 
effect). UNSAVEDEF takes the form 


Function: UNSAVEDEF 
# Arguments: 2 


Arguments: 1) an item, NAME 
2) a type identifier, TYPE 


Value: The type identifier, if successful. 


If TYPE is NIL, UNSAVEDFF looks for a definition under the EXPR prop- 
erty on the item’s property list. If no EXPR property exists, it will look for a 
CODE or SUBR property, and use their values, respectively, as the definition. 
UNSAVEDEF recognizes EXPR, CODE, and SUBR as values for TYPE to in- 
dicate that it should explicitly unsave a value only for that property. 

For example, we have saved the definition of SIGN under the EXPR prop- 
erty. Now, if we try to unsave a SUBR definition:: 


<(UNSAVEDEF 'SIGN 'SUBR) 
(SUBR not found) 


SAVEDEF and UNSAVEDEF are used by several INTERLISP subsystems 
to preserve the original body of the function. You may want to use them to pre- 
serve a definition via SAVEDEF before you modify it. Thus, if the modification 
is unsuccessful, you may recover the original definition via UNSAVEDEF. 


17.5.8 Loading a Definition 
You may load an arbitrary definition from the file using LOADDEF, which 
takes the form 

Function: LOADDEF 

# Arguments: 3 


Arguments: 1) the name of an object, NAME 
2) the type of the object, TYPE 
3) the source file, SOURCE 


Value: The definition of the object. 
LOADDEF retrieves the definition of the object NAME with the given type 


from SOURCE and assigns that definition to the object in memory. 
Consider the following example: 
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+-(OPENFILE 'AMIS ‘INPUT 'OLD) 
[DSK] AMIS :5 


*-(LOADDEF 'SLOTRECORD 'RECORD 'AMIS) 
SLOTRECORD 


*+-(RECLOOK 'SLOTRECORD) 
(RECORD SLOTRECORD 
(ID VALUE TYPE RELATION OFFSPRING) ) 


A Definition for LOADDEF 
We might define LOADDEF as follows: 


(DEFINEQ ) 
(loaddef (name type source) 
(PUTDEF name 


type 

(GETDEF name 
type 
source 


'(NODWIM NOCOPY) )) 
) 


17.5.9 Renaming an Object 


You may rename an object while preserving its value using RENAME, which 
takes the form 


Function: RENAME 
# Arguments: 5 


Arguments: 1) the old name, OLD 
2) the new name for the object, NEW 
3) a list of types for which objects are 
to be renamed, TYPES 
4) a list of files where renaming will be 
performed, FILES 
5) how the object will be renamed, METHOD 


Value: NEW, if successful. 
RENAME performs its function in three steps: 


1. Copies all instances of OLD to NEW for each type in TYPES. 
2. Calls CHANGECALLERS to change all occurrences of OLD to NEW. 
3. Deletes all instances of OLD via DELDEF. 
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Consider the following example. In our frame-based example, we have a 
function that we called CREATE.NODE. Suppose we want to change that func- 
tion to CREATE.FRAME. We do so via the following function call: 


(LOAD 'FRAME) 
(KAISLER) FRAME. .1 


*- (RENAME 'CREATE.NODE 'CREATE.FRAME 'FNS) 
(KAISLER)FRAME..1: 276 CREATE.NODE 8091 
editing the variables SHKFNS: 

CREATE. FRAME 


FILES and METHOD are described in the following section. 


17.5.10 Changing Calling Function Names 


When editing a large application, you may want to change the name of a func- 
tion to reflect a new capability, to reduce conflict with another name, or to be 
more semantic. However, the function may be utilized by many other functions 
in the program, particularly if it is a kernel function. Editing all functions that 
call the function can be a labor-intensive task. However, using Masterscope (see 
Chapter 26), INTERLISP can keep track of how a function is used and where it 
is used. CHANGECALLERS makes use of this knowledge about the structure of 
your program to perform these editing chores. It takes the form 


Function: CHANGECALLERS 
# Arguments: 5 


Arguments: 1) an old name, OLD 
2) a new name, NEW 
3) a list of object types, TYPES 
4) a list of files in which the objects 
may occur, FILES 
5) an editing method, METHOD 


Value: NIL. 


CHANGECALLERS finds all places where OLD is used as a type in 
TYPES. It changes all occurences of OLD to NEW in those locations. It also 
changes occurrences of OLD to NEW in all File Package commands so that you 
can remake the file easily. For example, 


-(CHANGECALLERS 'ADD.TO.NET 
"ADD. TO. FRAME. LIST 
"FNS 
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NIL 

'"MASTERSCOPE) 
-editing the functions CREATE.FRAME: 
-editing the variables FRAMEFNS 
-NIL 


CHANGECALLERS determines if OLD might be used as more than one 
type in a program. If so, it asks you if you want to edit each occurrence type 
rather than automatically making the change for you. For example, in our com- 
plex arithmetic example, suppose I wanted to change the object COMPLEX to 
CMPLX. I would do so as follows: 


<(CHANGECALLERS 'COMPLEX 'CMPLX) 
Warning -- COMPLEX is also used as (RECORDS FILES) 
«KAISLER)COMPLEX..2 263 299 362 COMPLEX CMULT CDIFFERENCE 
CZERO CPLUS 3852 3926 3983 4070 
editing the functions CMULT: 
(COMPLEX (DIFFERENCE & &) (PLUS & &)) 

Replace? 


editing the records COMPLEX: 
(DATATYPE COMPLEX (& &)) 

Replace? 
COMPLEX changed to CMPLX on COMPLEX 
NIL 


Note that you must also rename any object via RENAME if you use 
CHANGECALLERS as it only modifies those objects where the given object is 
used, but not the object itself. 

METHOD provides you with two alternatives in making the changes: 


1. If METHOD is EDITCALLERS, EDITCALLERS (see Section 19.1) is 
used to search FILES for all occurrences of OLD. 

2. If METHOD is MASTERSCOPE (see Chapter 26), the Masterscope da- 
tabase, if any, is used to locate all occurrences of OLD. If no MASTER- 
SCOPE database exists, it defaults to EDITCALLERS. 


If METHOD is NIL, the default is MASTERSCOPE. However, the default 
may be specified by the system variable DEFAULTRENAMEMETHOD which 
is initially NIL. You may force a default to MASTERSCOPE by setting the value 
of DEFAULTRENAMEMETHOD to MASTERSCOPE and creating a Mas- 
terscope database. Otherwise, it defaults to EDITCALLERS. 


4 
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17.5.11 Comparing Definitions 


You may compare the definitions of two objects of a given type in two versions of 
a file, or you may compare all the definitions of a given name for all object types 
across all sources. Two functions support this capability: COMPARE and 
COMPAREDEFS. 

COMPARE takes the form 


Function: COMPARE 
# Arguments: 5 


Arguments: 1) an object name, NAME-1 
2) an object name, NAME-2 
3) an object type, TYPE 
4) a source, SOURCE-1 
5) a source, SOURCE-2 


Value: T, if any differences; otherwise, NIL. 


COMPARE prints a list of differences, if any, to your terminal. COMPARE 
invokes COMPARELISTS to perform a comparison of the two definitions. It 
might be defined as: 


(DEFINEQ 
(compare (name-1 name-2 type source-1 source-2) 
(PROG (definition-1 definition-2) 

(SETQ definition-1 
(GETDEF name-1 type source-1)) 

(SETQ definition-2 
(GETDEF name-2 type source-2) ) 

(COND 

((COMPARELISTS definition-1 definition-2) 
x 


If no differences between the 
two definitions, merely return 
NIL. 
) 
(RETURN) ) ) 
(PRIN2 name-1 T T) 
(COND 
(source-1 
(SPACES 1 T) 
(PRIN1 "from" T) 
(PRIN2 source-2 T T))) 
(SPACES 1 T) 
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(PRIN1 "and" T) 

(PRIN2 name-2 T T) 

(COND 

(acateets’ 

(SPACES 1 T) 
(PRIN1 "from" T) 
(PRIN2 source-2 T T))) 

(SPACES 1 T) 

(PRIN1 "differ" T) 


(TERPRI T) 
(COMPARELISTS definition-1 definition-2) 
(RETURN T)) 
)) 
COMPAREDEFS takes the form 
Function: COMPAREDEFS 


# Arguments: 3 


Arguments: 1) an object name, NAME 
2) a list of object types, TYPES 
3) a list of object sources, SOURCES 


Value: An indication of the comparison of all 
occurrences of NAME. 


COMPAREDEFS uses COMPARELISTS to compare all occurrences of 
NAME as a type of TYPES in any source of SOURCES. It returns one of several 
values: 


1. If NAME is not found in any source in SOURCES, it returns (QUOTE 
(NOT FOUND)). 


2. If NAME occurs only once in any source of SOURCES, it returns 
(QUOTE (ONCE ONLY)), and there is no comparison to be made. 


3. If COMPARELISTS detects any differences, which are printed to your 
terminal, it returns (QUOTE DIFFERENT). 
4. Otherwise, it returns (QUOTE SAME). 


17.5.12 Determining Type Existence 
HASDEF allows you to determine if an object is a certain type. It takes the form 


Function: HASDEF 
# Arguments: 4 


Arguments: 


Value: 
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1) an object, NAME 

2) a type specifier, TYPE 

3) an object source, SOURCE 
4) a spelling flag, SPELLFLAG 


T, if NAME has a definition of TYPE. 


If HASDEF does not find any object with NAME of TYPE, it attempts 
spelling correction on NAME, and returns the spelling-corrected name. Other- 
wise, it returns NIL. Spelling correction is attempted only if SPELLFLAG is T. 


Consider the example: 


«-(HASDEF 'CMULT 'FNS 'COMPLEX) 


- 


+-(HASDEF 'CDIFERENCE 'FNS 'COMPLEX T) 


=CDIFFERENCE 


NIL 


17.5.13 Determining the Types of an Object 
TYPESOF allows you to determine the types of an object. It takes the form 


Function: 
# Arguments: 
Arguments: 


Value: 


TYPESOF 
4 


1) an object, NAME 

2) a list of possible types, POSSIBLE- 
TYPES 

3) a list of impossible types, IMPOSSIBLE- 
TYPES 

4) an object source, SOURCE 


A list of the types that are defined for 
NAME. 


TYPESOF returns a list of the types in POSSIBLE-TYPES, but not in IM- 
POSSIBLE-TYPES, for which NAME has a definition. If POSSIBLE-TYPES is 
NIL, FILEPKGTYPES is used. Consider the example: 


<(TYPESOF 'COMPLEX NIL NIL 'COMPLEX) 

(COMPLEX -- no entry on USERMACROS) 

(I.S.OPR COMPLEX not defined) 

(no READVICE property for COMPLEX) 

(RECORDS I.S.OPRS FNS FILES EXPRESSIONS ADVICE 


FILEPKGCOMS) 


606 The File Package 


Note that what TYPESOF returns is what COMPLEX could possibly be 
used as in COMPLEX, not how it is actually used. 


A Definition for TYPESOF 
We might define TYPESOF as follows: 


(DEFINEQ 
(typesof (name) 
(for TYPE inside FILEPKGTYPES 
when 
(HASDEF name TYPE) 
collect TYPE) 
)) 


17.6 DEFINING NEW FILE PACKAGE COMMANDS 


The File Package includes a large number of types that have been developed and 
defined based on the experience of the INTERLISP developers. In most cases, 
these types will cover the data structures that you are likely to build in your pro- 
grams. However, should you create unusual data structures, you may wish to 
build your own File Package commands to save and restore these data structures 
on a symbolic file. 


17.6.1 FILEPKGCOM 
FILEPKGCOM is the function that allows you to specify the characteristics of a 
new file package command. It takes the following form 

Function: FILEPKGCOM 

# Arguments: 1-N 


Arguments: 1) a command name, COMMAND 
2) a property name, PROPERTY 
3) a value for the property, VALUE 
4-N) property-value pairs 


Value: A list of the commands. 
FILEPKGCOM is a Lambda, Nospread function that will define new file 


package commands or change the attributes of existing commands. The proper- 
ties of the command are drawn from the following list: 


MACRO This property defines how to dump the 
command itself to a symbolic file. It 


For example, 
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isused by MAKEFILE when writing an 
expression to the symbolic file. 
VALUE has the form 


(<arguments) . <commands)) 


The arguments given to the command 
name are substituted for the 
{arguments) throughout (commands). 
The result is a list of File Package 
commands. 


(FILEPKGCOMS 'LISPXMACROS 


ADD 


"MACRO 

'(X (COMS * (MAKELISPXMACROSCOMS . 
X))) 

"CONTENTS 

'NILL) 


This property specifies how to add an 
instance of an object to a given File 
Package command. It is used by 
ADDTOFILE to update the <file)COMS 
list of a file. VALUE is a function, 
FN, of four arguments: 


. COM, a file package command 
. NAME, a typed object 

. TYPE, a type specifier 

. NEAR, a flag 


~-WNDN 


FN should return T if it adds NAME to 
COM; otherwise, NIL. 


Two possibilities exist: 


1. COM has the form 
(<com) * <filevar)) 


whence NAME is added to (CADDR 
COM) which should be a literal 
atom. 
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DELETE 


CONTENTS 


2. COM has the form 
(<com) <varlist)) 


whence NAME is added to the (CDR 
COM). 

3. TYPE is the type of the named 
object. 

4. NEAR, if non-NIL, specifies near 
which item ADDTOFILE should 
attempt to insert NAME (see 
ADDTOFILES?) . 


This property specifies how to delete 
an instance of an object from a File 
Package command. It is used by 
DELFROMFILES (see Section 17.7.2). 
VALUE is FN which is a function of 
three arguments corresponding to the 
first three arguments of ADD. FN 
returns T if it deletes NAME from 
COM, else NIL. If it returns ALL, COM 
should be interpreted as empty and 
may be deleted entirely from the 
command list. 


This property specifies whether or 
not an instance of an object of a 
given type is contained within a 
given File Package command. It is 
used by WHEREIS (see Section 17.3.8) 
and INFILECOMS? (see Section 17.7.3). 
VALUE is FN which is a function of 
three arguments corresponding to the 
three arguments of ADD. 


NAME is interpreted as follows: 


1. If NAME is NIL, FN returns a list 
of elements of type TYPE contained 
in COM. 

2. If NAME is T, FN returns T if 
there are any elements of type 
TYPE in COM. 

3. If NAME is any literal atom other 
than T or NIL, FN returns T if 
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NAME of type TYPE is contained in 
COM. 

4. If NAME is a list, FN returns a 
list of those elements of type 
TYPE contained in COM that are 
also contained in NAME. 


17.7 MANIPULATING FILE PACKAGE COMMANDS 


How a file is to be loaded is described by the File Package commands. A list of 
commands is usually stored as the value of the variable <filename)COMS. To 
create a file, you establish the content of <filename)COMS and execute MAKE- 
FILE (see Section 17.3.1). It uses the expressions found in the < filename )COMS 
expression as a guide to writing the symbolic form of the file. 

File Package commands may be very complex for large files containing 
many functions and initializing many variables. Moreover, the creation of un- 
usual structures often requires some ingenuity in describing them using stan- 
dard data structures or writing new functions to properly write them out and 
read them in. Managing these command lists may be quite difficult. To ease the 
burden, the File Package provides a set of functions for manipulating the 
(filename )COMS lists. 

Note that most if these functions are undoable. 


17.7.1 Adding To a File’s COMS 
ADDTOFILE adds an entry to the COMS list of a file. It takes the form 


Function: ADDTOFILE 
# Arguments: 3 


Arguments: 1) an object, NAME 
2) a file name, FILE 
3) a command type, TYPE 


Value: The file name. 
ADDTOFILE adds NAME of TYPE to the file package commands for 


FILE. For example, suppose I had an ugly variable that I wished to add to the 
file SHK. 


«(ADDTOFILE 'x 'shk 'uglyvars) 
SHK 


<SHKCOMS 
((FNS * SHKFNS) (VARS * SHKVARS) (UGLYVARS X)) 
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Adding to a Command List 

ADDTOCOMS adds an entry to a COMS list. It takes the form 
Function: ADDTOCOMS 
# Arguments: 3 


Arguments: 1) a command list, COMS 
2) an object, NAME 
3) a type, TYPE 


Value: T. 
The command list, COMS, may take one of two values: 


1. A variable whose value is a list of file package commands, i.e., MAP- 
COMS. 


2. A list of file package commands. 


<(ADDTOCOMS SHKCOMS 'X 'RECORD) 
NIL 


because ADDTOCOMS was unable to find a command of type RECORD in 
which to add X. On the other hand, 


<(ADDTOCOMS SHKCOMS 'Y 'VARS) 
T 


<-SHKCOMS 
((FNS * SHKFNS) (VARS * SHKVARS) (UGLYVARS X)) 


-SHKVARS 
(CURRENT .NETWORK.NODE Y) 


ADDTOCOMS “understands” how to add an entry to a ae file 
package command based on its form. 


17.7.2 Deleting from a File’s COMS 
DELFROMFILES deletes all instances of an object of a given type from the File 
Package commands associated with a file name. It takes the form 

Function: DELFROMFILES 

# Arguments: 3 


Arguments: 1) the name of an object, NAME 
2) an object type, TYPE 
3) a list of files, FILES 
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Value: A list of files from which NAME has been 
deleted. 


DELFROMFILES inspects the file package commands of all files that are 
named in FILES. It deletes NAME of TYPE from the appropriate commands in 
which it appears. If FILES is NIL, DELFROMFILES uses FILELST as its de- 
fault value. FILES may also be an atom whence (LIST FILES) is used. 

Consider the following example: 


<-(DELFROMFILES 'X 'UGLYVARS (LIST 'SHK)) 
(SHK) 

<— SHKCOMS 

((FNS * SHKFNS) (VARS * SHKVARS) (UGLYVARS) ) 


Deleting from a Command List 
DELFROMCOMS is used by DELFROMFILES to delete an object from a spe- 
cific file package command list. It takes the form 

Function: DELFROMCOMS 

# Arguments: 3 


Arguments: 1) a command list, COMS 
2) an object name, NAME 
3) an object type, TYPE 


Value: tT, 
COMS is usually the name of a <file)COMS variable that contains the defi- 


nition of the File Package commands for a file. DELFROMCOMS removes 
NAME from the specific command (e.g., sublist) within COMS according to its 


type. 
Consider the following example: 


«<-(DELFROMCOMS SHKCOMS 'Y 'VARS) 

T 

<SHKVARS 

(CURRENT . NETWORK . NODE) 
17.7.3 Determining if an Object is in a Command 
INFILECOMS? searches a File Package command list to determine if an object 
of a given type appears in the command list. It takes the form 

Function: INFILECOMS? 

# Arguments: 3 
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Arguments: 1) an object name, NAME 
2) a command list, COMS 
3) an object type, TYPE 


Value: T, if NAME of TYPE appears in COMS. 


COMS is usually a variable whose value is a list of File Package commands. 
INFILECOMS? searches its value looking for an instance of NAME in a com- 
mand associated with TYPE. It returns T if NAME is found. Consider the exam- 
ple: 


«-(INFILECOMS? 'MEDIAN AMISUTILCOMS 'FNS) 
T 


If NAME has the value NIL, INFILECOMS? will return a list of all objects 
with the type TYPE. Consider the example: 


«(INFILECOMS? NIL AMISUTILCOMS 'FNS) 
(INSERT.STRING DELETE.STRING SUBSTITUTE.STRING 
MAKE.STRING.FROM.LIST ...) 


If NAME has the value T, INFILECOMS? returns T if there are any objects 
of type TYPE in the command list. 


«-(INFILECOMS? T AMISUTILCOMS 'RECORD) 
NIL 


Obtaining A List of Object Types 
FILECOMSLST returns a list of the objects of type TYPE that appear in a file. 
It takes the form 


Function: FILECOMSLST 
# Arguments: 2 
Arguments: 1) a file name, FILE 
2) an object type, TYPE 
Value: A list of objects of type TYPE. 


FILECOMSLST searches the File Package commands associated with FILE 
for objects of type TYPE. It returns a list of all such objects, e.g., 


«-(FILECOMSLST 'AMIS 'RECORDS) 
(GRAPH.NODE SLOTRECORD DEMONRECORD) 
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Obtaining a List of Functions in a File 
We frequently ask for a list of all the functions in a file. FILEFNSLST returns a 
list of all functions that are named in File Package commands. It takes the form 


Function: 
# Arguments: 
Argument: 


Value: 


FILEFNSLST 
ei 
1) a file name, FILE 


A list of functions named in the File 
Package commands. 


Consider the following example: 


«-(FILEFNSLST 'AMIS) 
(CREATE.DATABASE.FUNCTIONS.MENU CREATE.DATA.MODELS 
MAKE.DB.COMS MAKE.DB.FILENAME ...) 


17.7.4 Making a New File Package Command 


MAKENEWCOM creates a new file package command that will dump an object 
of a type to a file when the file is (re)made. It takes the form 


Function: 
# Arguments: 
Arguments: 


Value: 


MAKENEWCOM 
2 


1) an object name, NAME 
2) an object type, TYPE 


The File Package command for dumping NAME 
of TYPE to a file. 


The command returned by MAKENEWCOM is usually appended to the 
File Package commands associated with a file, e.g., 


«(SETQ AMISUTILCOMS 
(APPEND AMISUTILCOMS (MAKENEWCOM 'VARIANCE 


(FNS VARIANCE) ) 


17.7.5 Creating a COMS Variable Name 


An operation that must frequently be performed is to create the name of the 
variable whose value is the list of File Package commands. This operation is 
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required because many File Package functions require that you only submit the 
name of the file. FILECOMS takes the form 


Function: FILECOMS 
# Arguments: 2 
Arguments: 1) a file name, FILE 
2) an object type, TYPE 
Value: An atom which is a variable name. 


If TYPE is NIL, then FILECOMS returns an atom of the form 
(file) COMS. Otherwise, it returns an atom composed from the file name and 
the object type. Consider the examples: 


«-(FILECOMS 'AMISMODELS) 
AMISMODELSCOMS 


«-(FILECOMS 'AMISNET 'VARS) 
AMISNETVARS 


17.7.6 Smashing a File’s COMS 


SMASHFILECOMS sets all file variables to NOBIND in a command list. It 
takes the form 


Function: SMASHFILECOMS 

# Arguments: 1 

Argument: 1) a file name, FILE 
Value: The file name. 


SMASHFILECOMS sets all file variables that appear in File Package com- 
mands to NOBIND. These variables take the form 


(<command) * <file variable)) 


It also sets the name of the command list variable to NOBIND. Consider the 
following example: 


<-SHKCOMS 
((FNS * SHKFNS) (VARS * SHKVARS) ) 


<-SHKFNS 
(CREATE.FRAME INITIALIZE.FRAME DEFINE.ATTRIBUTE ...) - 
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<—SHKVARS 
(CURRENT . NETWORK. NODE) 


+ (SMASHFILECOMS 'SHK) 
SHK 


<SHKCOMS 
UNBOUND ATOM 
SHKCOMS 


as are SHKFNS and SHKVARS. 


17.7.7 Moving an Item Between Files 
MOVETOFILE allows you to move an object of a given type from one file to 
another. It takes the form 

Function: MOVETOFILE 

# Arguments: 4 


Arguments: 1) a destination file, DSTFILE 
2) an object, NAME 
3) an object type, TYPE 
4) a source file, SRCFILE 


Value: The object name. 
MOVETOFILE is a shorthand notation for using DELFROMFILE and 


ADDTOFILE in the proper way to update the File Package commands of the 
two files. 


17.8 PRETTYPRINTING SYMBOLIC FILES 


In Section 15.7, we examined the functions for prettyprinting function defini- 
tions to a file or a terminal. When you make a symbolic file, the S-expressions 
comprising the function definitions and other forms are compressed to eliminate 
superfluous blanks and end-of-line characters. While storage efficient, these 
files are extremely difficult to read. You may create a symbolic file in pretty- 
printed format using the PRETTYDEF package. 


17.8.1 Prettyprinting Function Definitions 


PRETTYDEF writes a symbolic file, suitable for loading, in prettyprint format. 
It has the following form 


Function: PRETTYDEF 
# Arguments: 6 
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Arguments: 1) an list of functions, PRETTYFNS 
2) a file name, PRETTYFILE 
3) file package commands, PRETTYCOMS 
4) a list of functions, REPRINTFNS 
5) a file name, SOURCEFILE 
6) a list, CHANGES 


Value: The full name of the symbolic file. 


PRETTYDEF creates a symbolic file using the value of PRETTYFILE. If 
PRETTYFILE is NIL, the primary output file is used. If PRETTYFILE is an 
atom, its value is used as the file name. If the symbolic file is not already open, it 
will be opened by PRETTYDEF. It is automatically closed when PRETTYDEF 
terminates. 


«-(PRETTYDEF (LIST 'IMAG)) 
(DEFINEQ 
(IMAG (LAMBDA (CX) **COMMENT** 
(RECORDACCESS (QUOTE IMAG) 
CX NIL (QUOTE FETCH))))) 
T 


where the primary output file is used. 

If PRETTYFILE is a list, the symbolic file name is assumed to be the CAR 
of the list. Processing is the same except that the file will not be closed when 
PRETTYDEF terminates. 

PRETTYENS is an optional list of functions that are to be printed on the 
symbolic file. If PRTTYFNS is NIL, PRETTYDEF assumes the form (FNS * 
<prttyfns)>) will appear in the file package commands. 


«-(PRETTYDEF NIL NIL COMPLEXCOMS NIL 'COMPLEX) 
(RPAQQ COMPLEXCOMS (COMPLEX REAL IMAG CPLUS CDIFFERENCE 


RECIPROCAL TRUNCATE PRINT.ARRAY)) - 
(DEFINEQ 
(COMPLEX (LAMBDA (R I) **COMMENT** 


All of the functions in COMPLEXCOMS will be prettyprinted to the pri- 
mary output file, since no functions are specifically identified. 

PRETTYCOMS is a list of file package commands. If PRETTYCOMS is an 
atom, its value is used. PRETTYDEF writes an RPAQQ on the file which sets 
the atom to the command list when the file is loaded. 

REPRINTENS and SOURCEFILE are used when a file is remade (see Sec- 
tion 17.3.2). REPRINTFNS is a list of functions to be printed. If its value is 


17.8 Prettyprinting Symbolic Files 617 


EXPRS, all functions with EXPR definitions will be prettyprinted. If its value is 
ALL, all functions with EXPR definitions or EXPR properties will be printed. 

SOURCEFILE is the name of a file from which to copy the definitions of 
those functions that are not going to be prettyprinted, i.e., those not specified by 
REPRINTENS. If SOURCEFILE is T, the most recent version of PRETTY- 
FILE is used. Thus, when you make the next version of PRETTYFILE, you can 
directly copy the definitions of any functions that have not changed from the 
previous version. If there is no previous version, PRETTYDEF prints the mes- 
sage ‘‘< prettyfile) NOT FOUND, SOIT WILL BE WRITTEN ANEW”. It then 
proceeds as if REPRINTFNS and SOURCEFILE were both NIL. 

CHANGES is for internal use by the File Package. 


A Definition for PRETTYDEF 
We might define a simple version of PRETTYDEF as follows: 


(DEFINEQ 
(prettydef (prettyfns prettyfile prettycoms) 
(PROG (save-output-file closefile? 
prettycomlist prettydate) 
(* 


Save the output file name. 


*) 
(SETQ save-output-file (OUTPUT) ) 
(COND 
((LISTP prettyfile) 
(* 
If PRETTYFILE is a list, 
get its CAR which is the 
actual file name, and note 
that it should not be 
closed when PRETTYDEF 
terminates. 
*) 
(SETQ prettyfile (CAR 
prettyfile) ) 
(SETQ closefile? T))) 
(* 
If PRETTYFNS is NIL or an atom which 
is not a list and PRETTYCOMS is NIL 
or an atom which is not a list, there 
is no specification from which 
PRETTYDEF can work. Declare an error. 
) 
(AND 


(NLISTP prettyfns) 
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(NLISTP (EVALV prettyfns) ) 

(NLISTP prettycoms) 

(NLISTP (EVALV prettycoms) ) 

(ERROR "ILLEGAL OR MEANINGLESS CALL:" 
(LIST 'PRETTYDEF 


prettyfns 
prettyfile 
prettycoms) ) ) 
COND 
((NULL prettyfile) 
(* 


If PRETTYFILE is NIL, 
output is directed to the 
primary output file, which 
you cannot close. 

) 

. (SETQ closefile? T)) 
((OPENP prettyfile 'OUTPUT) 
(* 


Attempt to open the output 


file. 
) 
(OUTPUT prettyfile) ) 
(T 
(OUTFILE prettyfile) 
(SETQ prettydate 
(PRINTDATE 
(NAMEFIELD 
prettyfile) 
'PRETTYDEF) ) ) ) 
(SETQ prettyfile (OUTPUT) ) 
(COND 
((OR 
(LISTP prettyfns) 
(LISTP (CAR prettyfns) )) 
(PRINTFNS prettyfns) 
(PRETTYCOM prettyfns T))) 
(COND : 
( (AND 


(NLISTP prettycoms) 
(NLISTP (CAR prettycoms) ) ) 
(GO out))) 
(* 
Print the File Package commands in a 
prettyprinted format. Each command 
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type must be treated according to its 
own characteristics. 
) 
(PRETTYCOM prettycoms T) 
(COND 
((ATOM prettycoms) 
(SETQ prettycoms (CAR prettycoms) ) )) 
(SETQ prettycomlist prettycoms) 
loop 
(COND 
((NLISTP prettycomlist) 
(GO out))) 
(PRETTYCOM (CAR prettycomlist) ) 
(SETQ prettyl (CDR prettycomlist) ) 
(GO loop) 


(* 


out 
Restore the primary output file. 


) 
(OUTPUT saveout) 
(COND 
((NULL closefile?) 
(* 
If NIL, close the output 
file. 
) 
(ENDFILE prettyfile) 
(EVAL prettydate) )) 
(RETURN prettyfile) ) 


17.8.2 Printing a Definition 


PRINTDEF prints any expression in pretty format on the primary output file. It 
takes the form 


Function: PRINTDEF 
# Arguments: 6 


Arguments: 1) an expression, EXPRESSION 
2) a left hand margin, LEFTMARGIN 
3) a definition flag, DEFFLG 
4) a tail flag, TAILFLG 
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5) a font list, FONTLST 
6) a file name, FILE 


Value: NIL. 


PRINTDEF usually prints the value of EXPRESSION on the primary out- 
put file using the primary readtable. If FILE is non-NIL, the output from 
PRINTDEF will be directed to the specified file, which must be opened for out- 
put. 

LEFTMARGIN determines the number of spaces from the logical left end 
of the output display. Thus, 


«-(PRINTDEF <expression) ) 


will result in the expression being printed abutting the left edge of your display 
terminal. The value of (LINELENGTH) determines the right hand margin. 

If DEFFLG has the value T, then the value of EXPRESSION is treated as a 
function definition. Special action is taken for LAMBDAs, PROGs, CONDs, 
comments, and CLISP words. Otherwise, no special action is taken. DEFFLAG 
is NIL when PRINTDEF calls PRETTYPRINT to print variables and property 
lists or when the editor calls PRINTDEF via PPV. 

If TAILFLG has the value T, then EXPRESSION is treated as the tail of a 
list which should be printed without parentheses. 

FONTLST is used by the Font Package which is not discussed in this text. 

Consider the following example: 


«-(PRINTDEF complexcoms 10 NIL T) 
(FNS * COMPLEXFNS) 
(RECORDS COMPLEX) 
(P (DEFPRINT (QUOTE COMPLEX) 
(FUNCTION PRINT.COMPLEX) ) ) 
NIL 


«-(PRINTDEF (GETD 'RECIPROCAL) 5 T T) 
LAMBDA (X) **COMMENT** 
(COND 
((EQP X 0.0) 
(ERROR "ZERO HAS NO RECIPROCAL") ) 
(T 
(QUOTIENT 1.0 (FLOAT X)))) 
NIL 


17.8.3 Making a File Creation Slug 


FILECREATED prints a message followed by the time and date the file was 
made. FILECREATED takes the following form 
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Function: FILECREATED 

# Arguments: 1 

Argument: 1) an expression, EXPRESSION 
Value: NIL. 


FILECREATED is an NLAMBDA, nospread function. 

The time and date of file creation are found in the CAR of EXPRESSION. 
The message is the value of the variable PRETTYHEADER, which is initially 
set to the string “FILE CREATED:”’. If PRETTYHEADER is NIL, nothing will 
be printed. 

The CDR of EXPRESSION contains information about the file. Since 
FILECREATED is usually called by PRINTDATE, this information is already 
properly formatted. 

FILECREATED stores the time and date the file was made on the file’s 
property list under the property FILEDATE. 

Consider the following example: 


«-(SETQ file-info (CONS (DATE) NIL))) 
("'18-SEP-84 20:09:06") 


*-(APPLY (FUNCTION FILECREATED) file-info) 
FILE CREATED 18-SEP-84 20:09:06 
NIL 


17.8.4 Obtaining the File Date 


You may obtain the file date by invoking FILEDATE, which takes the following 
form 


Function: FILEDATE 

# Arguments: 1 

Argument: 1) a file name, FILE 

Value: The file date in the FILE CREATED 
expression. 


FILEDATE returns the date contained in the FILE CREATED expression 
stored in the file header, e.g., 


«-(FILEDATE 'COMPLEX) 
"'30-AUG-84 20:44:36" 
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17.8.5 Printing the File Date 


PRINTDATE is usually called by PRETTYDEF to insert the “FILE CRE- 


ATED” aaproan at the beginning of a symbolic file. It takes the following 
format 


Function: PRINTDATE 
# Arguments: 2 
Argument: 1) a file name, FILE 
2) a list of changes, CHANGES 
Value: The expression which is the CONS of the 


date and CHANGES. 


CHANGES is used by the File Package commands to insert an expression of 
the form 


changes to: (FNS ...) 


in the “FILE CREATED” expression. 

PRINTDATE calls upon DATE (see Section 29.1.1) to return the current 
date and time as a string suitable for printing in a symbolic file. 

Consider the following example: 


<(PRINTDATE T NIL) 
(FILECREATED "18-SEP-84 20:17:52" T) 
( ("18-SEP-84 20:17:52" T)) 


Note that if there are no changes to the file, PRINTDATE inserts the value 
T as a placeholder. 

An alternative definition for PRINTDATE which provides more informa- 
tion might be defined by you as: 


(DEFINEQ 
(printdate (file format source-date previous-source-date 
compile-date previous-compile-date) 
(PROG (slug) 


(SETQ slug 
(NCONC 
(LIST 'FILEHEADER 
file 
(LIST 'DATE (DATE) ) 
(LIST 'FORMAT 


(OR format "SPECIAL") ) 
(LIST ‘FILENAME 
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( FILEVERSION (OUTPUT) ) ) 
(LIST 'SOURCE-DATE 
(OR source-date (DATE) ))) 
(COND 
(previous-source-date 
(LIST 
(LIST 'PREVIOUS-SOURCE-DATE 
previous-source-date) ) ) ) 
(AND compile-date 
(LIST 
(LIST 'COMPILING-DATE 
compile-date) )) 
(AND previous-compile-date 
(LIST 
(LIST 'PREVIOUS-COMPILE- 
DATE 
previous-compile- 
date) ) ) 
)) 
(PRINTDEF1 slug) 
(RETURN slug) ) 
)) 


17.8.6 Printing Function Definitions on a File 


PRINTENS prints DEFINEQ on the primary output file. It then prettyprints the 
definitions of functions which are given as its argument. It takes the form 


Function: PRINTFNS 

# Arguments: 1 

Argument: 1) a list of functions, FNSLST 
Value: NIL. 


Usually, PRINTFNS is given a variable of the form <file)FNS from a File 
Package command which has the form: 


(FNS * <file)FNS) 


Alternatively, if the function names are distributed in the File Package com- 
mands in the form: 


(FNS <filename1) ... <filenameN)) 


624 _—s The File Package 


PRINTENS may be called with (CDR <expression)). Yet a third form is 
(PRINTFNS (FILEFNSLST <filename)) ) 


which gathers into a list all of the function names defined in the file. 
Consider the following example: 


«-(PRINTFNS (LIST 'ROUNDTO) ) 
(DEFINEQ 
"  (ROUNDTO 
(LAMBDA (X Y) **COMMENT** 
(TIMES (ROUNDED (QUOTIENT X Y) 


Y))))) 
NIL 


«-(PRINTFNS 'ADD3) 
(DEFINEQ) 
NIL 


17.8.7 Printing a COMS Message upon Loading 


PRETTYCOMPRINT prints the value of its argument using LISPXPRINT un- 
less the value of PRETTYHEADER is NIL. Usually, its argument is the name of 
the variable containing the File Package commands for a file. It takes the form 


Function: PRETTYCOMPRINT 

# Arguments: 1 

Argument: 1) an expression, EXPRESSION 
Value: NIL. 


PRETTYCOMPRINT is an NLAMBDA function. It prints the value of 
EXPRESSION. 

When you load a file, LOAD prints certain information about the file name 
and when it was created. It then begins executing S-expressions that it reads 
from the file. Normally, the first of these S-expressions displays the File Package 
command variable. 

If PRETTYHEADER is NIL, nothing will be printed by PRETTYCOM- 
PRINT. Thus, if you want to load a file without alerting the user that you have 
done so, you might temporarily bind PRETTYHEADER to NIL while you load 
the file. 


17.8.8 Obtaining the File Changes 


FILECHANGES prints the changes to the file stored in the file header expres- 
sion at the beginning of the file. It takes the form 
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Function: FILECHANGES 
# Arguments: 2 
’ Arguments: 1) a file name, FILE 
2) a file package type, TYPE 
Value: A list of the changed objects of type 
TYPE. 


FILECHANGES inspects the changes expression at the beginning of the 
file. It returns a list of all the changes of the given type. If TYPE is NIL, FILE- 
CHANGES returns an association list (alist) of all changes where the file pack- 
age type is the CAR of the alist. 


«-(FILECHANGES 'FRAME) 
((FNS ADD.TO.FRAME.LIST CREATE.FRAME INITIALIZE. FRAME) 
(VARS SHKFNS) ) 


17.9 SYMBOLIC FILE INPUT 


Programs are usually stored in source form in symbolic files on mass storage. To 
create an Interlisp application environment, we load one or more symbolic files 
into the Interlisp virtual memory. Symbolic files are created in two ways: 


1. Using a text editor to type in source code. 
2. Using MAKEFILE to write out function definitions and other informa- 
tion as directed by File Package commands. 


As we have seen in previous sections, the File Package writes a considerable 
amount of information describing an application environment into a file. As ap- 
plications grow in complexity, a symbolic file may contain a large number of 
functions. It may be time-consuming to load all of the information from the file. 
The File Package provides a number of functions for loading all or portions of a 
symbolic file. 


17.9.1 Generalized Load 


LOAD is the generalized loading function. It reads successive S-expressions 
from a file until it encounters the atom STOP. Each S-expression is evaluated as 
it is read. It takes the form 


Function: LOAD 
LOAD? 


# Arguments: 3 
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Arguments: 1) a file name, FILE 
2) a load flag, LDFLG 
3) a print flag, PRINTFLAG 


Value: The file name or NIL. 


LOAD expects the file to exist when it accesses it. If it does not, LOAD 
_ prints the message FILE NOT FOUND followed by the file name. 

If LOAD encounters an end-of-file condition, it displays an error message ? 
and breaks. : 

Because each S-expression is evaluated as it is read, erroneous S-expressions 
can cause a break to occur. Depending on how you handle the break, loading 
may not be completed. 

PRINTFLAG may be used to trace the loading of S-expressions. If 
PRINTFLAG has the value T, LOAD prints the value of each S-expression; 
otherwise, it does not. Consider the following example: 


«(LOAD 'COMPLEX T T) 

<KAISLER) COMPLEX. .2 

FILE CREATED 30-AUG-84 20:44:36 

NIL © 

COMPLEXCOMS 

COMPLEXCOMS 

((FNS * COMPLEXFNS) (RECORDS COMPLEX) ...) 
(COMPLEX REAL IMAG CPLUS CMULT ...) 


«KAISLER) COMPLEX. .2 


LDFLG affects the evaluation of DEFINE(Q) and RPAQ(Q) functions. 
DFNFLG (see Section 8.2.4) is bound to LDFLG while LOAD executes. LDFLG 
may take the values: 


NIL 

If LDFLG is NIL, and a function is redefined (e.g., a definition already exists in 
the virtual memory), LOAD displays the message (<{function-name) REDE- 
FINED) and saves the old definition on the atom’s property list. Thus, you may 
recover the original (in memory!) definition of the function using UNSAVE- 
DEF. 


T 
If LDFLG is T, the old definition is overwritten. You are not informed that the 
function has been overwritten. 


PROP 

If LDFLG has the value PROP, function definitions are stored on the atom’s 
property list under the property EXPR. This action is the corollary to (1) where 
the old definition is saved. Here, the new definition is saved on the property list. 
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ALLPROP 
If LDFLG has the value ALLPROP, both function definitions and variables set 
by RPAQ(Q) are stored on property lists. 


SYSLOAD 

LDFLG has the value SYSLOAD, LOAD does not load debugging and develop- 
ment information. The resulting application will execute more efficiently. 
LOAD takes the following actions: 


a. Binds DFNFLG to T. 

b. Binds LISPXHIST to NIL so that the loading operation is not undoable 
(see Section 28.2). 

c. Binds ADDSPELLFLG to NIL to suppress adding names to spelling 
lists. (see Section 22.7.2). 

d. Binds FILEPKGFLG to NIL so that the file is not noticed by the File 
Package. 

e. Binds BUILDMAPFLG to NIL to prevent construction of a file map. 

f. Binds the -COMS and -VARS entries to NOBIND. 

g. Adds FILE to SYSFILES rather than FILELST. 


An alternative form, LOAD?, operates the same except that it does not load 
the file if it has already been loaded. In this case, its value is NIL. 


17.9.2 Loading Selected Functions 


Rather than loading an entire file, you may load selected functions and variables 
from a file. LOADFNS takes the form 


Function: LOADFNS 
# Arguments: 4 


Arguments: 1) a list of functions, FNS 
2) a file name, FILE 
3) a load flag, LDFLG 
4) an S-expression, VARS 


Value: A list of functions found and loaded as 
well as those not found. 


FNS may be a list of functions, or a single function name, or T. The latter 
case forces all functions to be loaded. FILE may be either a compiled or symbolic 
file. LDFLG is handled exactly the same as in LOAD. 

VARS specifies how to handle expressions other than function definitions. 
There are several possible values: 
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1. T, which loads all expressions. 

- NIL, which load none of the expressions. 

VARS, which loads only expressions created by RPAQ(Q). 
FNS/VARS, which loads only -COMS and -BLOCKS expressions. 
. Any other atom is treated as (LIST <atom)). 


- If VARS is a list, all atoms in the list are compared to the CARs of each 
expression. Wherever a match is found, the expression will be loaded. 


LOADENS returns a list of functions loaded as well as those not found. The 
format of the list is: 


(<{loaded-functions) (NOT-FOUND: <not-found-functions)) ) 


If VARS was non-NIL, the list will also include those expressions that were 
loaded as well as those members of VARS (as a list) which were not found. 

If FILE is NIL, WHEREIS (see Section 17.3.8) is invoked to locate the file 
containing the first function in FNS. It assumes that all functions will be loaded 
from that file. | 


17.9.3 Loading Selected Expressions 
LOADVARS loads S-expressions from a file. It takes the form 


Function: LOADVARS 
# Arguments: 3 


Arguments: 1) a variable list, VARS 
2) a file name, FILE 
3) a load flag, LDFLG 


Value: A list of variables loaded. 


This form is equivalent to 


(LOADFNS NIL (file) <ldflg) <vars)). 


17.9.4 Editing Functions Without Loading 


When the File Package has noticed a file, it knows about its contents. At that 
point, you can edit functions within a file without consuming memory to load 
them. To notice a file in this manner, you may use LOADFROM, which takes 


the form 


Function: LOADFROM 
# Arguments: 3 
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Arguments: 1) a file name, FILE 
2) a list of functions, FNS 
3) a load flag, LDFLG 


Value: The file name. 
Typically, LOADFROM is used to notice a file, e.g., 


*-(LOADFROM 'ADV15.DCOM) 
[KAISLER]ADV15.DCOM;2 


You may load a few functions in addition to noticing the file by providing a 
second argument. LOADFROM is equivalent to: 


(LOADFNS <fns) <file>) <ldflg) T). 


17.9.5 Loading from a Compiled File 
LOADCOMP loads expressions from a compiled, rather than symbolic, file. It 
takes the form 

Function: LOADCOMP 

# Arguments: 2 


Arguments: 1) a file name, FILE 
2) a load flag, LDFLG 


Value: The file name. 


LOADCOMP performs all the functions on a file associated with compila- 
tion. That is, it evaluates all expressions included in DECLARE: EVAL@COM- 
PILE expressions. It notices the function and variable names by adding them to 
the lists NOFIXFNSLST and NOFIXVARSLST. 


18 





Error Handling 


Errors occur frequently during programming, particularly in the early stages of 
program development. During this period, easy handling of errors is a necessity 
because it is likely that you will be encountering many of them. As a program 
ages, most of the obvious errors are eliminated. It is the subtle errors, mainly 
due to logic or complex data structures, that begin to plague the programmer. 
Now, what is needed is not easy handling, but powerful tools to diagnose the 
cause of the error and determine the corrective action. The process of isolating 
the error and finding the fix is often labor-intensive in these latter stages of pro- 
gram development. 

INTERLISP provides a powerful facility for catching and handling errors as 
they occur. Unlike other programming languages where the user may merely 
inspect the state of the program after an error occurs, INTERLISP allows the 
user to interactively correct the problem and continue the computation. IN- 
TERLISP also provides a set of tools that can assist you in isolating errors within 
program segments and identifying their causes. This duality of capability is one 
of the reasons that INTERLISP is a powerful and flexible program development 
environment. 


18.1 HOW ERRORS OCCUR 


Errors can occur for many reasons. A discussion of error types is presented in 
Section 18.5. However, because of the simplicity of datatypes and representa- 
tions in INTERLISP, errors frequently occur for a few well-defined reasons. 

The most frequent case is an unbound atom. When atoms are created, their 
value cell is filled with the atom NOBIND to indicate that they have not been 
assigned a value. When the interpreter encounters an atom whose value cell con- 
tains NOBIND, it generates an error. It does so by calling the function 
FAULTEVAL. FAULTEVAL will print the character string ““U.B.A.”’ to indi- 
cate an unbound atom and then break. 
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The second most frequent cause of errors is an attempt to invoke a function 
which is undefined. This error is often due to a misspelling either in the function 
definition or, more likely, in the statement where the function is to be invoked. 
Another case occurs when the interpreter encounters a list in EVAL mode whose 
CAR is not the name of a function. The interpreter calls FAULTEVAL which 
normally prints ““U.D.F.”, to indicate an undefined function, and then breaks. 

Other types of errors are usually specific instances of these generic errors. 
They are specifically identified because they usually occur in primitive functions 
and occur frequently in the early stages of program development. Specializing 
the error helps you identify the cause more rapidly. There are over fifty different 
errors currently detected in INTERLISP. Some are specific to the implementa- 
tion while others are detected in every implementation. Section 18.5 discusses 
the generic errors. Most of these errors will cause a break to occur and place your 
computation under the control of the Break Package. 

Once inside the Break Package, the user may perform any number of opera- 
tions to diagnose and correct the error. These operations are discussed in Chap- 
ter 20. 


18.2 CATCHING AND HANDLING ERRORS 


A good dose of preventative medicine often prevents a program from going awry 
and causing significant damage to your environment or computation. Catching 
errors as they occur but before they have a deleterious effect allows you to pre- 
vent any damage that might occur. This approach is useful for two reasons: 


1. It makes your programs user-friendly if you can alert the user when an 
error occurs, provide him with information on how to correct it, and al- 
low him to do so. 

2. When you attempt to account for errors in your program, it makes you 
think carefully about potential faults and plan for their occurrence. This 
is good software engineering practice. 


INTERLISP provides a mechanism for catching a subset of the errors that 
can occur before they cause a break. When the error is caught, the user may 
analyze it and decide whether or not to break, break sometimes (depending on 
other factors), or take corrective action. Another mechanism allows a user to 
provisionally execute a function, determine whether an error would occur or not, 
and proceed based on this information. These two mechanisms are discussed in 
the following sections. 


18.2.1 Catching Errors: ERRORTYPELST 


ERRORTYPELST is a system variable that is used by FAULTEVAL to deter- 
mine how an error should be handled. ERRORTYPELST is a list of lists each 
having the format 


eee 
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(<number) <expressionl) ... <(expressionN)) 


The (number) is one of the error numbers described in Section 18.5. The 
<expression )s are INTERLISP code for handling the error. If an error number 
does not appear on ERRORTYPELST, then an error of that type will always 
cause a break. 

ERRORTYPELST is used by BREAKCHECK to determine whether or not 
an error should cause an invocation of FAULTEVAL. ERRORTYPELST is 
searched for an entry with a CAR corresponding to the type of error that has 
occurred. If it is found, then the expression )s are evaluated. If the last (expres- 
sion) produces a non-NIL value, that value is substituted at the point where the 
error occurred and the function is re-entered. 

Consider the following example [irm83] which defines ERRORTYPELST to 
have an entry for catching errors of the type NON-NUMERIC ARG. The form of 
the entry is 


(SETQ ERRORTYPELST 
(10 
(AND 
(NULL (CADR ERRORMESS) ) 
(SELECTQ (STKNAME ERRORPOS) 
((IPLUS ADD1 SUB1) 0) 


(ITIMES 1) 
(PROGN 
(SETQ BREAKCHK T) 
NIL) )))) 


Whenever a NON-NUMERIC ARG error occurs, this entry will force the 
error to be caught. When the expression is evaluated, we see that only specific 
cases are to be treated. These are 


1. The offending value is NIL, derived from 
(NULL (CADR ERRORMESS) ) 


2. If the function executed was IPLUS, ADD1, or SUB1, then substitute 
the value 0. 
3. If the function executed was ITIMES, substitute 1. 


Otherwise, break on any other occurrence of this error. This is achieved by 
setting BREAKCHK to T, not by returning NIL. The reason for this is that once 
the expression is evaluated, the value returned will be substituted in the offend- 
ing statement. In this case, returning NIL will, of course, cause the error to re- 
cur. 
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When you use the ERRORTYPELST facility, you may examine and set the 
following system variables: ERRORMESS, ERRORPOS, BREAKCHK, and 
PRINTMSG. 

ERRORMESS is a list whose CAR is the number of the error and whose 
CADR is the offending value. In the above example, the CADR of ER- 
RORMESS is NIL. This yields the subcase ““NON-NUMERIC ARG NIL” that 
we treat in the expression. 

. ERRORPOS is the position on the stack where the error occurred. In partic- 
ular, it will be a pointer to the name of the function in which the error occurred. 
We obtain the name of the function by using STKNAME (see Section 30.3.2) to 
retrace the pointer to the PRIN1-PNAME of the function. 

BREAKCHK determines whether or not a break will occur after the expres- 
sion is evaluated. Note that since the expression returns a value, a break only 
occurs if the value causes another error. By setting BREAKCHK to T, you may 
force a break to occur regardless of the value returned. Conversely, setting 
BREAKCHK to NIL means that a break will not occur. 

PRINTMSG indicates that the error message will be printed (T) or not 
(NIL). To force this action, you should include a SETQ expression in the <ex- 
pression) that explicitly sets PRINTMSG. 


18.2.2 An Example of ERRORTYPELST Usage 


The ERRORTYPELST mechanism allows you to intercept the handling of an 
error and determine its disposition. You may decide to handle it yourself or allow 
the system to proceed with the standard processing. If you you want to handle an 
error yourself, you must place an entry on the ERRORTYPELST. 

A common error that causes significant problems to many INTERLISP pro- 
grammers is the case where a file will not open. Usually, this error arises because 
the file does not exist in the current directory (although on certain implementa- 
tions, you may not be able to open it if it is already opened by another user). 

The LISPUSERS package, FILEWONTOPEN, adds an entry to ERROR- 
TYPELST to handle the problem where a file will not open. The entry is defined 
as follows: 


(ADDTOVAR 
ERRORTYPELST 
(9 
(PROG NIL 
loop 
( AND 
(SELECTQ (STKNAME ERRORPOS) 
(INFILE NIL) 
((OUTFILE DRIBBLE) T) 
(OPENFILE 
(SELECTQ (STKARG 3 
ERRORPOS) 
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(OLD NIL) 
(NEW T) 
(SELECTQ (STKARG 2 
ERRORPOS) 
_ ((INPUT BOTH) NIL) 
(OUTPUT T) 
NIL) )) 
((OPENF *PROG*LAM) 
(STKNTH -1 ERRORPOS ERRORPOS) 


(GO loop) ) 
NIL) 
(NOT (FILENAMEFIELD (CADR ERRORMESS ) 
'VERSION) ) 
(RETURN 
(PACKFILENAME 
"VERSION 
(ADD1 
( FILENAMEFIELD 
(OUTFILEP (CADR 
ERRORMESS ) ) 
'VERSION) ) 
"BODY 


(CADR ERRORMESS) )))))) 


18.3 CATCHING ERRORS IN A COMPUTATION 


In planning for errors, you must be able to evaluate the expression that could 
cause the error. ERRORSET allows you to evaluate an expression and return a 
value that specifies whether an error occurred or not. 

The generic format for invoking ERRORSET is 


Function: 
# Arguments: 
Arguments: 


Value: 


ERRORSET 
2 


1) an S-expression to be evaluated, 
EXPRESSION 
2) a flag, FLAG 


Either a list containing the value of 
the evaluated S-expression or NIL. 


ERRORSET is a LAMBDA-type function. Thus, its arguments are evalu- 
ated before passing them to ERRORSET. That is, ERRORSET performs (effec- 
tively) (EVAL (EVAL EXPRESSION)). The (EVAL EXPRESSION) is per- 
formed before ERRORSET is entered. If no error occurs in the evaluation of the 
S-expression, the value of ERRORSET is a list containing the value obtained by 
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evaluating the S-expression. Otherwise, ERRORSET returns NIL. Note that if 
the value of the S-expression is NIL, ERRORSET returns the value (NIL). Thus, 
to retrieve the value of EXPRESSION, you must take the CAR of the value re- 
turned by ERRORSET. 

ERRORSET evaluates EXPRESSION via (EVAL EXPRESSION). If no er- 
ror occurs as the result of evaluating EXPRESSION, ERRORSET returns the 
value of the computation as the sole element of a list. For example, 


«(SETQ CITIES 
(LIST 'SAN-FRANCISCO 'NEW-YORK 'BALTIMORE) ) 
(SAN-FRANCISCO NEW-YORK BALTIMORE) 


«-(ERRORSET '(CAR CITIES) ) 
(SAN-FRANCISCO) 


Note that I have QUOTE4d the expression (CAR CITIES) because ERROR- 
SET applies EVAL to it. Without quoting, we would have 


«<-(ERRORSET (CAR CITIES) T) 
UNBOUND ATOM 

SAN-FRANCISCO [in ERRORSET] 
NIL 


If an error occurs during the evaluation of EXPRESSION, ERRORSET re- 
turns NIL. 


«<-(ERRORSET '(IPLUS 'X 128)) 
NIL 


where the obvious error is the usage of ‘X in the IPLUS expression. Executing 
the same statement with FLAG equal to T yields 


«-(ERRORSET '(IPLUS 'X 128) T) 
NON-NUMERIC ARG 

X 

NIL 


FLAG determines whether or not any error message resulting from the eval- 
uation of EXPRESSION will be printed. It may take the following values: 


1. T, whence the error message is printed. 
2. NIL, whence no error messages are printed. However, if NUSETQGAG 
is NIL, error messages are printed regardless of the value of FLAG. 


3. INTERNAL, whence this invocation is ignored for purposes of determin- 
ing whether or not to print an error message. ERRORSET was called 


18.3 Catching Errors ina Computation 637 


from within INTERLISP as an error prevention mechanism. The error 
will be handled when it is detected, so there is no reason to notify the 
user. 

4. NOBREAK, whence no break will occur. However, a break occurs if the 
error occurs more than HELPDEPTH levels below the errorset. 


18.3.1 Alternative Forms of ERRORSET 


Two alternative forms of ERRORSET allow you to use prespecified values for 
FLAG. ERSETQ and NLSETQ take the form 


Function: ERSETQ 
NLSETQ 
# Arguments: 1 
Arguments: 1) an S-expression, EXPRESSION 
Value: The value produced by evaluating 


EXPRESSION; otherwise, NIL. 


Both ERSETQ and NLSETQ are NLAMBDA functions, so their arguments 
are not evaluated before the function is invoked. 


Consider the following example: 
<(ERSETQ (ITIMES a b)) 
is equivalent to 
«<-(ERRORSET (QUOTE (ITIMES a b)) T) 


Note that we do not QUOTE arguments to ERSETQ and NLSETQ. 


Defining ERSETQ and NLSETQ 
We might define them as follows: 
(DEFINEQ 
(ersetq 
(NLAMBDA (expression) 
(ERRORSET expression T) 
))) 
(DEFINEQ 
(nlsetq 


(NLAMBDA (expression) 


638 Error Handling 


(ERRORSET expression NIL) 
))) 


The value of FLAG determines whether or not error messages are printed 
when. ERRORSET is called. This value may be superseded by the value of 
NLSETQGAG. Its value is initially T, meaning don’t print error messages. By 
setting NLSETQGAG to NIL, all error messages will be printed regardless of the 
value of FLAG. The effect of NUSETQGAG is to force INTERLISP to treat all 
NLSETQs as ERSETQs. 


18.3.2 Checking for an End of File 


In INTERLISP/370, the function READC does not return an indication of an 
end-of-file condition. Rather, it causes an error to occur. However, you may 
check for an end-of-file condition using ERRORSET and PEEKC. A function 
that might be defined is shown below: 


(DEFINEQ 
(check-end-of-file (file-name) 
(COND 
((ERSETQ (PEEKC file-name)) 'end-of-file) ) 
)) 


PEEKC (see Section 14.2.7) “‘looks-ahead”’ in the read buffer to see what 
the next character is. If there is no character in the buffer and the system cannot 
fill the buffer with more data, an end-of-file condition results. BY applying ER- 
SETQ, if the end-of-file condition occurs, CHECK-END-OF-FILE will return 
NIL. Otherwise, it returns a list consisting of the single character that would 
normally be returned by PEEKC. 


18.4 TERMINAL-INITIATED BREAKS 


Most errors and breaks occur within functions due to logic errors or because you 
have explicitly invoked BREAK from within a function. You may also initiate a 
break from your terminal. There are several reasons for breaking a program 
from your terminal: 


1. You notice the program has entered an infinite loop that is performing 
the same function over and over again. 

2. Your program has failed to display the expected output and you desire to 
determine where it is in the computation. 

3. You will attempt to debug your program which has produced a notice- 
able error in its execution. 

4. You are attempting to determine what a program does given little or no 
documentation (either externally or internally) and perhaps no access to 
the source code. 
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You may initiate a break from your terminal by typing an interrupt charac- 
ter. The interrupt characters differ for the particular implementation of IN- 
TERLISP. Consult the IRM to determine the interrupt characters for your im- 
plementation. 

You may disable or redefine existing interrupt characters or define new in- 
terrupt characters. An interrupt character is associated with an interrupt chan- 
nel. INTERLISP-10 has nine predefined interrupt channels: 


Channel Interrupt Type 

CTRL-D RESET 

CTRL-E ERROR 

CTRL-B BREAK 

CTRL-H HELP 

CTRL-P PRINTLEVEL 

CTRL-T CONTROL-T (timing statistics) 
<DEL) RUBOUT (character deletion) 
CTRL-S STORAGE 

CTRL-O OUTPUTBUFFER 


INTERLISP-D does not support the STORAGE and OUTPUTBUFFER 
interrupt channels. 

An interrupt may be either hard or soft. A hard interrupt takes place as soon 
as it is typed. A hard interrupt always forces the system out of the function it is 
currently executing. The stack is unwound to the last function call or to the top 
level if a CTRL-D is typed in. For example, CTRL-E and CTRL-D are hard 
interrupts. Soft interrupts do not occur until the next function call. Soft inter- 
rupts may be safely “continued from” without loss of data or control in the com- 
putation. CTRL-T is an example of a soft interrupt. 

A hard interrupt is implemented by generating error 43. The corresponding 
expression from USERINTERRUPTS is retrieved once ERRORX is entered by 
the system. 

A soft interrupt is implemented by calling INTERRUPT with an appropri- 
ate third argument. The corresponding expression is retrieved from USERIN- 
TERRUPTS. When a soft interrupt character is typed at your terminal, IN- 
TERLISP clears and saves the input buffer, and rings the bell to alert you that it 
has received the interrupt. The interrupt expression is evaluated. Depending on 
the result, the input buffers are restored and the computation proceeds. 

In either case, if the character you have typed in is defined as an interrupt 
character, but no definition is found on USERINTERRUPTS, INTERLISP 
generates an error message ““ UNDEFINED USER INTERRUPT” and forces a 
break. 
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18.5 TYPES OF ERRORS 


INTERLISP provides error indications for over fifty types of errors. Each error is 
indicated by a numeric code and an associated message. The numeric code is 
returned by ERRORN. The alphanumeric string will be printed by ER- 
RORMESS. Some errors are implementation dependent, and thus are unde- 
fined in other versions of INTERLISP. 


Error 0: System Trap Error 

Error code 0 corresponds to a “SYSTEM ERROR”. This error also occurs in the 
INTERLISP-10 system, where it is displayed as “JSYS ERROR”. It is unde- 
fined in INTERLISP/370. 

For INTERLISP-10, JSYS errors occur if you attempt to execute an operat- 
ing system function with the wrong code or parameter setup. It may also occur if 
you are programming directly in ASSEMBLE code. Usually it occurs because of 
addressing problems due to smashed data structures. 

The IRM advises that you abandon (e.g., reload) a system that exhibits this 
behavior. 


Error 1: Unused Error 
This error code is not used in any of the current INTERLISP implementations. 


Error 2: Stack Overflow 

Error code 2 corresponds to a “STACK OVERFLOW”. This error usually oc- 
curs as the result of a runaway computation. The computation calls too many 
nested functions or binds to many variables in the functions that it calls. 

One way to invoke this error in INTERLISP/370 is by attempting to trace 
EVAL. The TRACE function (see Section 20.1.1) calls EVAL internally to eval- 
uate the expression which is its argument. 

Another way is to begin a recursive computation where the number of levels 
of recursion exceeds the stack depth. For example, trying to count the number of 
cells in a circular list using a recursive function that operates on successive tails 
of the list. 


Error 3: Illegal Return 
Error code 3 corresponds to an “ILLEGAL RETURN”. This error results when 
a program attempts to execute a RETURN expression while not executing 
within a PROG form. 

Note that a call to RETURN may occur in a function called from within a 
PROG in another function. 


Error 4: Argument Not a List 
Error code 4 corresponds to “ARG NOT LIST”. This error results when the 
function invoked expects a list as its argument. 

One common error is passing an atom as the first argument of RPLACA or 
RPLACD rather than a list. For example, 
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*-(RPLACA 'X (LAST X)) 
ARG NOT LIST 
X 


Error 5: File System Error 

Error code 5 corresponds to ‘HARD DISK ERROR”. This error code is cur- 
rently defined for INTERLISP-D but not for INTERLISP-10 or INTERLISP/ 
370. This error indicates that something is wrong with the integral disk used in 
Xerox 11xx systems. You should consult a Field Engineer if this error occurs. 


Error 6: Setting NIL 

Error code 6 corresponds to ““ATTEMPT TO SET NIL OR T”’. This error 
results when the first argument of SET or SETQ is NIL. Usually, you will en- 
counter this error when INTERLISP attempts to evaluate an argument to SET 
whose value is NIL. 


Error 7: Attempting to Replace NIL 
Error code 7 corresponds to ‘““ATTEMPT TO RPLAC NIL”. It occurs when you 
attempt to RPLACA or RPLACD NIL with something other than NIL. 


Error 8: Invalid Goto 

Error code 8 corresponds to “UNDEFINED OR ILLEGAL GO”. This error 
occurs when a program attempts to execute (GO <label)) while not within a 
PROG form or when <label) is undefined within the PROG. 


Error 9: Unable to Open a File 

Error code 9 corresponds to “FILE WON’T OPEN”’. This error occurs when a 
program executes one of the File Package functions that open a file. Usually, the 
file does not exist in the current directory. 


Error 10: Non-numeric Argument 
Error code 10 occurs when a numeric function expects a number as an argu- 
ment. For example, 


<(IPLUS 'five 10) 
NON-NUMERIC ARG 
FIVE 


Error 11: Atom Too Long 

Error code 11 corresponds to the error ““ATOM TOO LONG”. This error occurs 
when you attempt to a create an atom with a PRINI-PNAME whose length is 
greater than the maximum number of characters allowed by your implementa- 
tion. Usually, it will occur if you type an atom name that is too long, if you try to 
create an atom name via PACK, or you read an atom name from a file. The first 
and last cases are generally due to typing errors and may be easily corrected. 
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Error 12: Atom Hash Table Filled 

Error code 12 corresponds to ‘“‘ATOM HASH TABLE FULL”. The atom hash 
table is used to store pointers to each of the atoms in the system in order to speed 
reference to their particular storage locations. It is possible to exceed the size of 
the atom hash table. Usually, the atom hash table starts with an initial size and 
expands automatically until the maximum allowable size is reached. For IN- 
TERLISP-10, this limit is approximately 32,767 atoms. 


Error 13: File Not Open 

Error code 13 corresponds to ““FILE NOT OPEN”’. Most input and output func- 
tions as well as many of the File Package functions expect the file that they will 
operate on to be open. If the file is not open, this error is generated. 


Error 14: Argument Not a Literal Atom 

Error code 14 corresponds to “ARG NOT LITATOM”. sitesiy INTERLISP 
primitives expect an atom as an argument. This error is generated when the 
argument is determined to be something other than a literal atom. . 


Error 15: Too Many Files Open 

Error code 15 corresponds to “TOO MANY FILES OPEN’’. Different imple- 
mentations set a limit on the number of files that your program may have open 
simultaneously. Usually, this number is about 32. Because the terminal is always 
open and available for input/output, it is not included in the open file count. 


Error 16: End of File Encountered 

Error code 16 corresponds to “‘END OF FILE”. This error occurs when an input 
function attempts to read past the end of a file. After the error occurs, the file is 
closed. 

This error can be very disconcerting to most users. It probably should be 
handled better, i.e., some indication of an end-of-file condition being returned 
without causing an error. 

You may process this error by placing an entry on ERRORTYPELST to 
intercept it. Your code may or may not close the file, but should return some 
indication of an end-of-file condition. The IRM suggests that you return “‘]”’ as 
an indication meaning the end of a list. 


Error 17: Error 

Error code 17 corresponds to “ERROR”. It is produced when the function ER- 
ROR is called with one or more messages appropriate to the particular function 
that generated the error. You may also want to use this error code for errors 
occurring within your programs. 


Error 18: CTRL-B condition 
Error code 18 corresponds to “‘BREAK’’. This error occurs when you type a 
CTRL-B during the execution of a program. Your computation is placed under 
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the control of the BREAK package (see Chapter 20) at the current execution 
point. 


Error 19: Illegal Stack Argument 

Error code 19 corresponds to “ILLEGAL STACK ARG”’. This error occurs 
when a stack manipulation function is given an argument other than a stack 
position. The most common case occurs when you attempt to specify a stack 
position via a function name which cannot be found in the stack. See Chapter 30 
for a discussion of the Stack Functions. 


Error 20: Evaluation Fault 
Error code 20 corresponds to ““FAULT EVAL”. This occurs while INTERLISP 
is being loaded (bootstrapped) into memory. Once FAULTEVAL is defined, 
this error should not occur. 


Error 21: Array Space Exceeded 

Error code 21 corresponds to ‘ARRAYS FULL”. As mentioned earlier, IN- 
TERLISP divides available memory into a number of pools corresponding to the 
basic datatypes that it supports. When array space is exceeded, INTERLISP 
first attempts a garbage collection on the array space. If this does not produce 
enough array space, then this error message is generated. 

This error usually occurs because you have created too many arrays or tried 
to create an array with unusually large dimensions. The latter case occurs when 
you specify arguments to ARRAY which compute the size of the array. If your 
arguments produce erroneous dimension information, you will receive this error. 


Error 22: File System Space Exceeded 

Error code 22 corresponds to ““FILE SYSTEM RESOURCES EXCEEDED”. 
This error occurs when the number of files that you have written exceeds the 
current file space. For INTERLISP-10, this may be attempting to exceed the 
limits imposed upon your directory concerning number of files, file blocks, or 
size. In INTERLISP-D, it often occurs when you attempt to exceed the capacity 
of the integral disk in the Xerox 11xx machines. 


Error 23: Non-existent File 
Error code 23 corresponds to ““FILE NOT FOUND”. This error occurs when 
you attempt to open a file which does not exist in the specified directory. It may 
also occur if the file name is ambiguous (i.e., when several files have the same 
file name but different extensions). 

ERRORTYPELST is initialized to handle this error as follows: 


(SETQ ERRORTYPELST 
"(23 
(SPELLFILE (CADR ERRORMESS) ) ) ) 
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where SPELLFILE will search alternative directories or perform spelling correc- 
tion on the directory or file name to determine the proper file. 


Error 24: Damaged SYSOUT File 

Error code 24 corresponds to ‘‘BAD SYSOUT FILE”. This error occurs when 
the date of the sysout file (see Section 16.9.1) do not correspond to the data on 
which the current version of INTERLISP was made. It also occurs if you attempt 
to load a file via SYSIN which is not a sysout file. 


Error 25: Bad CDR Argument 
Error code 25 corresponds to “UNUSUAL CDR ARG LIST”. This error occurs 
when an expression ends in a non-list other than NIL. For example, 


«(CONS T . 3) 
UNUSUAL CDR ARG LIST 
Z 


Error 26: Hash Table Space Exceeded 

Error code 26 corresponds to ‘HASH TABLE FULL”. This error occurs when 
you attempt to hash more items into a hash table than it has room to store. See 
Section 11.3. 


Error 27: Illegal Argument 

Error code 27 corresponds to “ILLEGAL ARGUMENT”. This error is dis- 
played when INTERLISP does not have a specific error message to produce. It is 
used by many functions within INTERLISP. Actually, errors of this sort should 
be better handled, but no one has taken the time to rewrite the internal code to 
categorize them. 


Error 28: Non-Array Argument 

Error code 28 corresponds to “ARG NOT ARRAY”. This error occurs when an 
array function is given an argument which is not an array address. See Section 
11.1. 


Error 29: Illegal Block 

Error code 29 corresponds to “ILLEGAL OR IMPOSSIBLE BLOCK’”’. This 
error occurs in INTERLISP-10 when you attempt to get or release an additional 
block of memory. 


Error 30: Already Released Stack Pointer 

Error code 30 corresponds to “STACK PTR HAS BEEN RELEASED”. This 
error occurs when you give a stack function a stack pointer that is no longer 
defined, because it has been released. See Chapter 31. 
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Error 31: Memory Space Exceeded 

Error code 31 corresponds to “STORAGE FULL”. This error occurs when the 
available memory space has been entirely allocated. Usually, it occurs after a 
garbage collection when the garbage collector has not been able to find any unal- 
located space. This error may occur (in lengthy computations) if you allocate 
space for various objects, but fail to retain their addresses via SETQ. The space 
is consumed, but disappears from your virtual memory. You cannot address if 
you do not retain a pointer to it, and it cannot be garbage collected for the same 
reason. 

This error will also occur if your computation is too large for the available 
memory space. For example, the Xerox 1108/1186 machines have a virtual 
memory space of 32 Mbytes. It is fairly easy for large computations to exceed this 
memory space after some interval. When an error of this sort occurs, you may be 
placed in RAID. 


Error 32: Incorrect Object Types 

Error code 32 corresponds to “ATTEMPT TO USE ITEM OF INCORRECT 
TYPE”. This error occurs in Record Package functions and in functions associ- 
ated with accessing user-defined datatypes (see Chapter 27). This error is gener- 
ated if the type of change to be made to a field of a user datatype does not corre- 
spond to the datatype of the object. 


Error 33: Illegal Datatype Number 

Error code 33 corresponds to “ILLEGAL DATATYPE NUMBER”. This error 
occurs when you present a user-defined datatype function with an invalid field 
specifier. See Chapter 27. 


Error 34: Datatype Space Exceeded 

Error code 34 corresponds to “DATATYPES FULL”. The memory pool avail- 
able in which to allocate descriptions of user-defined datatypes is limited. When 
this pool is full, this error will be generated. 


Error 35: Binding NIL or T 

Error code 35 corresponds to ‘““ATTEMPT TO BIND NIL OR T”’. This error 
occurs in PROG and LAMBDA expressions where you declare NIL or T as a 
dummy variable and attempt to assign it a value. For example, 


«(PROG ((NIL <expression))) ...) 
ATTEMPT TO BIND NIL OR T 
NIL 


Error 36: User Interrupt Characters Exceeded 

Error code 36 corresponds to “TOO MANY USER INTERRUPT CHARAC- 
TERS”. INTERLISP currently provides for nine user interrupt channels. At- 
tempting to enable an additional user interrupt character will cause this error. 
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Error 37: Read Macro Error 

Error code 37 corresponds to ‘‘READ-MACRO CONTEXT ERROR”. This er- 
ror occurs when READ is executed within a read macro function and the next 
token is ) or ]. See Section 14.4. 


Error 38: Illegal Read Table 
Error code 38 corresponds to “ILLEGAL READTABLE”, This error occurs 


when you provide an illegal address to one of the read table functions (see Sec- 
tion 14.5). 


Error 39: Illegal Terminal Table 

Error code 39 corresponds to “ILLEGAL TERMINAL TABLE”. This error oc- 
curs when you provide an illegal address to one of the terminal table functions 
(see Section 15.5). 


Error 40: Swap Block Too Large 

Error code 40 corresponds to ““SWAPBLOCK TOO BIG FOR BUFFER”. This 
error occurs in INTERLISP-10 when you attempt to swap in a function or an 
array which exceeds the size of the swapping buffer. Consult the IRM (page 
22.26) for further details. 


Error 41: Protection Violation 

Error code 41 corresponds to ‘PROTECTION VIOLATION”. This error oc- 
curs in INTERLISP-10 when you attempt to open a file that you do not have 
clearance to access or you attempt to reference an unassigned device. Consult 
the host operating system manual. 


Error 42: Illegal File Name 
Error code 42 corresponds to ‘BAD FILE NAME”. This error occurs when you 
provide a badly formed file name to one of the File Package functions. The error 
will be generated by the host operating system when it attempts to resolve the file 
name in the disk directory. 


Error 43: User Break 
Error code 43 corresponds to ‘USER BREAK”’. This error occurs when you 
generate a hard user interrupt character, e.g., CTRL-B, CTRL-D, etc. 


Error 44: Unbound Atom 

Error code 44 corresponds to ““‘UNBOUND ATOM”. This error occurs when 
you attempt to reference an atom which has not been defined. The atom is cre- 
ated, but its value cell contains NOBIND. For example (assuming X was previ- 
ously defined), 


<(SETQ X 'NOBIND) 
(X reset) 
NOBIND 
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+X 
UNBOUND ATOM 
X 


The atom has no stack binding due to a PROG or LAMBDA expression, nor 
a top level value. The atom which generated the error can be retrieved via 
(CADR ERRORMESS). 


Error 45: Undefined Expression CAR 

Error code 45 corresponds to “UNDEFINED CAR OF FORM”. This error oc- 
curs when EVAL attempts to evaluate an expression whose CAR is not a valid 
function name. The atom may exist, but it has no definition in the function cell. 


«(EVAL (X Y)) 
UNDEFINED CAR OF FORM 
X 


Error 46: Undefined Function 

Error code 46 corresponds to ‘UNDEFINED FUNCTION”. This error occurs if 
APPLY is given as its first argument an atom which does not have a function 
definition. For example, 


«(APPLY 'X (LIST 'A 'B 'C)) 
UNDEFINED FUNCTION 
X 


Error 47: CTRL-E Error 
Error code 47 corresponds to ““CONTROL-E”’. This error is generated when you 
type a CTRL-E at your terminal. 


Error 48: Floating Point Underflow 
Error code 48 corresponds to “FLOATING UNDERFLOW”. This error is gen- 
erated in INTERLISP-D only during a floating point operation. 


Error 49: Floating Point Overflow 
Error code 49 corresponds to “FLOATING OVERFLOW”. This error is gener- 
ated in INTERLISP-D only during a floating point operation. 


Error 50: Overflow 
Error code 50 corresponds to “OVERFLOW”. This error is generated in IN- 
TERLISP-D only during an integer operation. 


Error 51: Illegal Hash Array 
Error code 51 corresponds to ‘ARG NOT HARRAY”. This error is generated in. 
INTERLISP-D only when a hash array function is given an address which does 


648 Error Handling 


not point to a hash array. Note that INTERLISP-D allocates separate memory 
pools for arrays and hash arrays and can thus detect the distinction easily. 


Error 52: Too Many Arguments 

Error code 52 corresponds to “TOO MANY ARGUMENTS”. This error is gen- 
erated in INTERLISP-D only when the evaluation function detects that a 
LAMBDA spread or nospread, or an NLAMBDA spread function has been 
given too many arguments. This error is generated by the Xerox 11xx machine 
microcode. 


18.6 ERROR HANDLING FUNCTIONS 


INTERLISP provides a powerful and flexible error handling environment. It is 
usually possible for you to write programs that can recover from almost any type 
of error. To do so, however, you must be able to analyze the error occurrence. 
When it is not possible to recover from an error, you must be able to provide 
sufficient information to enable the user to diagnose the problem and correct it. 
The functions described in this section are used to provide various types of infor- 
mation about the occurrence of errors. 


18.6.1 Printing Error Messages 


Several functions allow you to print standard error messages that are augmented 
with additional information. 

ERROR prints one or two error messages and causes a break to occur. It 
takes the form 


Function: ERROR 
# Arguments: 3 


Arguments: 1) a message, MESSAGE1 
2) a message, MESSAGE2 
3) a break flag, NOBREAKFLAG 


Value: NIL. 
When ERROR is called, it prints MESSAGE1 and MESSAGE? as follows: 


1. MESSAGE1L is printed using PRIN1. If MESSAGE is an atom, a space 
is printed, and then MESSAGE2 is printed using either PRIN1, if it is a 
string, or PRINT, if it is anything else. 

2. If MESSAGE is not an atom, then after it is printed using PRIN1, a 
carriage return is printed, and then MESSAGE2 as described above. 

3. If MESSAGE1 and MESSAGE2 are both NIL, the message will simply 
be ERROR. 
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If NOBREAK is T, ERROR prints its messages and calls ERROR! (see be- 
low). Otherwise, it executes 


(ERRORX 17 (CONS MESS1 MESS2) ) 


which leaves the decision as to whether to print any messages and cause a break 
up to BREAKCHECK. 


A Definition for ERROR 
We might define ERROR as follows: 
(DEFINEQ 
(error (messagel message2 nobreakflag) 
(COND 
(nobreakflag 
(* 
Print the error messages, but do 
not break the computation here. 
) 
(SETERRORN 17 
(CONS message1 message2) ) 
(ERRORMESS1 messagel message2 'ERROR) 
(ERRORB) ) 
(T 
( ERRORX 
(LIST 17 
(CONS messagel 
message2) )))) 
)) 


ERRORB is an internal function that is implementation dependent. 


Printing Help Messages 
An alternative function is HELP. It takes the form 


Function: HELP 
# Arguments: 2 


Arguments: 1) a message, MESSAGE1 
2) a message, MESSAGE2 


Value: The value returned from the breakpoint. 
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HELP prints its messages like ERROR and then calls BREAK1 (see Section 
20.3.3). If MESS1 and MESS2 are both NIL, HELP merely prints HELP! before 
calling BREAK1. For example, 


«-(HELP "An example of HELPing"') 
AN EXAMPLE OF HELPING 
NIL 


(HELP broken) 


A Definition of HELP 
We might define HELP as follows: 


(DEFINEQ 
(help (message1 message2) 
(ERRORMESS1 message1 message2 aes) 
(BREAK1 (ERROR "2?" 'G T) 
be 
HELP) 
)) 


Printing a Warning to the User 
SHOULDNT calls HELP with the message ‘‘Shouldn’t Happen!”’. It takes the 
form 


Function: SHOULDNT 

# Arguments: 0 

Arguments: N/A 

Value: No value returned. 


HELP and SHOULDNT provide you with different ways of signaling un- 
usual conditions in your program. HELP indicates that the program has entered 
a region that it normally would not enter at this stage of the computation. A 
good use is to signal an erroneous data value which you might allow the user to 
correct. On the other hand, SHOULDNT indicates that the program should 
never have encountered the situation that it finds itself in. 


< (SHOULDNT) 
"Shouldn't Happen" 


(HELP broken) 
: STOP 

(Note: no value returned!) 
5 ae 
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Generalized Message Printing Functions 
ERRORMESS is a generalized message printing routine that prints an error 
message corresponding to an ERRORN form. It takes the form 


Function: ERRORMESS 

# Arguments: 1 

Argument: 1) an ERRORN form, ERRORFORM 
Value: NIL. 


ERRORMESS prints a message corresponding to the ERRORN form. For 
example, 


*«-(ERRORMESS '(12 T)) 
ATOM HASH TABLE FULL 
a 

NIL 


A Definition for ERRORMESS 
We might define ERRORMESS as follows: 


(DEFINEQ 
(errormess (error-expression) 
(COND 
((NULL error-expression) 
(* 
Retrieve error form corresponding 
to the last error that occurred. 
) 
(SETQ error-expression (ERRORN) ))) 
(COND 
((EQUAL (CAR error-expression 17) 


(x 
) 


(SETQ error-expression 
(CADR error-expression) ) 
(ERRORMESS1 (CAR error-expression) 
(CDR error-expression) ) ) 


17 signals a general error code. 


(AND LISPXHISTORY 
(LISPXPUT 'ERROR 
(CADR error- 
expression) ) ) 
(ERRORM error-expression) ) ) 


)) 
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ERRORMESS1 
The workhorse function for printing error messages for many of these functions 
is ERRORMESS1. It takes the form 


Function: ERRORMESS1 
# Arguments: 3 


Arguments: 1) a message, MESSAGE1 
2) a message, MESSAGE2 
3) a message, MESSAGE3 


Value: NIL. 


ERRORMESS1 prints the messages for HELP and BREAK functions. We 
might define ERRORMESS1 as follows: 


(DEFINEQ 
(errormess1 (message1 message2 message3) 
(PROG (a-message) 
(COND 
( (AND 
(NULL message1) 
(NULL message2) ) 
(* 
If MESSAGE1 and MESSAGE2 
are null, print MESSAGE3 
and return. 
) 
(LISPXPRINT message3 T) 
(RETURN) ) ) 
(LISXPRIN1 message1 T) 
(COND 
((OR 
(ATOM message1) 
(STRINGP message2) ) 
(* 
If MESSAGE1 is an atom or 
MESSAGE2 is a string, print 
a space and MESSAGE2. 
) 
(LISPXSPACES 1 T)) 
(T 
(LISPXTERPRI T))) 
(SETQ a-message message1) 
(COND 
((STRINGP message2) 
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(LISPXPRIN1 message2 T) 
(LISPXTERPRI T)) 


(T 
(SETQ a-message message2) 
(LISPXPRINT message2 T))) 
(AND 
LISPXHISTORY 


(LISPXPUT 'ERROR a-message) ) 
)) 


Note that A-MESSAGE records the proper message for insertion into the 
history list. 


18.6.2 Returning from Errors 
There are two ways to return from an error: ERROR! and RESET. 
ERROR! takes the form 
Function: ERROR! 
# Arguments: 0 
Arguments: N/A 
Value: 2? (not to be trusted) 
ERROR! operates like a programmable CTRL-E. When executed, it imme- 


diately returns from the most recent ERRORSET or RESETLST (see Section 
2.7) 


Resetting the System State 
RESET operates like a programmable CTRL-D. It forces an immediate return 
to the top level of INTERLISP. It takes the form 

Function: RESET 

# Arguments: 0 

Arguments: N/A 

Value: NIL 


RESET clears the stack of all frames associated with the previous computa- 
tion. 


+ (RESET) 


RESET is often issued from within the Break Package when one discovers 
that the environment has become too entangled to decipher. 
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Note, however, that issuing a RESET does not re-initialize your environ- 
ment. Thus, any objects that you have created in the computation thus far will 
remain defined. This “detritus” can affect the re-execution of your program, 
particularly if it expects to find certain things uninitialized or having certain 
values. 


18.6.3 Obtaining Information about Errors 


ERRORN returns a form that describes the last error that occurred. It takes the 
form : 


Function: ERRORN 

# Arguments: 0 

Arguments: N/A 

Value: An expression (error #) . ¥, 


The error number is the index of the last error that occurred. X is the expres- 
‘ sion that was printed or would have been printed after the error message (e.g., 
the value of MESSAGE1). 


Defining New Error Messages 
You may define new error messages using the SETERRORN, which takes the 
form 


Function: SETERRORN 
# Arguments: 2 


Arguments: 1) an error number, NUMBER 
2) an error message, MESSAGE 


Value: The error number. 


SETERRORN may be used to redefine any of the existing system error mes- 
sages (usually with longer, more detailed messages) or to define a new error mes- 
sage. INTERLISP-D supplies over fifty error messages. You may use numbers 
greater than 52 for you own error messages. 

The best way to initialize error messages for a program is to place SETER- 
RORN calls in the P command list of the File Package commands. These calls 
are evaluated when the file is loaded, and so are part of the initialization of your 
environment. 

If you define new error messages, I recommend that you categorize them 
according to the type, location, and severity of error. You should also assign you 
error messages numbers beginning with 200 to avoid possible future conflict with 
INTERLISP error messages. 
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Obtaining the Error Message 


ERRORSTRING returns the string which represents the message associated 
with an error number. It takes the form 


Function: ERRORSTRING 

# Arguments: 1 

Arguments: 1) an error number, NUMBER 

Value: The string, if any, associated with the 


indicated error number. 


ERRORSTRING is primarily used to allow you to obtain an error message 


which you may then edit via the string handling functions before printing via 
ERROR. 


*-(ERRORSTRING 10) 
"NON-NUMERIC ARG" 


ERRORSTRING is used when you want to tailor the error messages more 
specifically to conditions that arise within your program. Since you may inter- 


cept the printing of error messages, you may obtain the basic string and edit it to 
be more informative for the user. 


18.6.4 Entering the Error Routines 
The general entry point to the error routines is ERRORX, which takes the form 


Function: ERRORX 

# Arguments: 1 

Argument: 1) an error message form, ERRORFORM 
Value: The value returned by the exit from the 


error routines. 


If ERRORFORM is NIL, ERRORN is used to determine the error. Other- 
wise, ERRORFORM should have the form: 


(<number) . <message) ) 


whence ERRORX calls SETERRORN with the CAR and CDR of the form to 
(re)define the error message. 

ERRORX calls BREAKCHECK to determine whether an error should oc- 
cur or not. If no break occurs, it prints the message and returns from the last 
ERRORSET. 
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A Definition for ERRORX 
We might define ERRORX as follows: 


(DEFINEQ 
(errorx (errorform) 
(ERRORX2 
(COND 
(errorform 
(* 
Caller has provided error 
number and message. 


(SETERRORN (CAR errorform) 
(CADR errorform) ) 
errorform) 


(* 


(T 


Use the error number and 
message determined by the 
system. 
) 
(ERRORN) ) ) 
(STKNTH -1 'ERRORX) ) 
)) 


ERRORXz2 is the workhorse that actually performs all of the functions asso- 
ciated with handling errors. We might define it as follows: 


(DEFINEQ 
(errorx2 (error-message error-position) 
(PROG (culprit array-size array-address esgag 
frame-name fn-type breakchk) 
(COND 
( (AND 

(EQ (CAR error-message) 26) 
(SETQ culprit (CADR error-message) ) 
(LISTP culprit) ) 
(* 


Error was a hash table overflow. 
) 
(SETQ array-size 
(ARRAYSIZE (CAR culprit))) 
(SETQ array-address (CDR culprit) ) 
(SETQ array-address 
(HARRAY 
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(COND 
((NULL array-address) 
(FTIMES array-size 
1.5)) 
((FLOATP array-address) 
(FTIMES array-size 
array- 
address) ) 
((NUMBERP array-address) 
(IPLUS array-size 
array- 
address) ) 
(T 
(GO top))))) 
(RPLACA culprit 
(REHASH (CAR culprit) 
array-address) ) ) 
(RETURN culprit) )) 
(SETQ breakchk 
(BREAKCHECK error-position 
(CAR error-message) ) ) 
top 
(COND 
( (AND 
ERRORTYPELST 
(SETQ culprit 
(ASSOC (CAR error-message) 
ERRORTYPELST) ) 
(SETQ culprit (EVAL (CADR culprit) ))) 
(* 
If there are entries on 
ERRORTYPELST and the error is 
represented by one of those 
entries, then evaluate the form 
found there to handle the error. 


(RETEVAL 
error-position 
(SUBPAIR 
'(FN ARGS) 
(LIST 
( LINKSTKNAME 
(STKNAME error-position) 
error-position) 
(SUBST 
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culprit 
(CADR error-message) 
(STKARGS error- 
position) )) 
"(APPLY 'FN 'ARGS)))) 
((NULL esgag) 
(* 


Do not suppress the error 
message 


(ERRORMESS error-message) ) ) 


errorb 
(COND 
((NULL breakchk) 
(* 
The error will occur at the 
actual position in the code. 
) 
(RETEVAL 
(STKNTH 1 error-position) 
'ERRORB) ) ) ) 
(SETQ frame-name (STKNAME error-position) ) 
(COND 
((NOT (LITATOM frame-name) ) 
(SETQ frame-name 
(LINKSTKNAME frame-name 
error-position) ))) 
(COND 
((EQ (CAR error-message) 10) 
(* 


Non-numeric argument to 
arithmetic function. 


) 
(LISPXPRIN1 'IN T) 
(LISPXPRINT frame-name T) 
(SETQ result 
' (BREAK1 
(ERROR '? 'G T) 
r 
NIL 
NIL 
ERRORX) ) ) 
(GO exit) ) 
(SETQ fn-type 
(SELECTQ (FNTYP frame-name) 
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((SUBR* FSUBR FSUBR*) 
'(ERROR 'CANT 'G T)) 
((EXPR FEXPR EXPR* FEXPR* ) 
(CONS 'PROGN 
(CDDR (GETD frame-name) ) ) ) 


(NIL 
(CONS 'PROGN 
(CAR 
(VAG 
(ADD1 
(LOC frame-name) ))))) 
(SUBR 
(RPLACD (STKARG 1 error-position) 
'U) 
(RPLACD (STKARG 2 error-position) 
'v) 


(CONS frame-name '(U V))) 
(SAVED1 fn-type 
frame-name 
(ARGLIST frame-name) ) ) ) 
(SETQ result 
(LIST 'RETFROM 
(LIST (QUOTE QUOTE) error- 


position) 
(LIST 'BREAK1 
culprit 
T 
frame-name 
'ERRORX) ) ) 
exit 
(RETEVAL 
(STKNTH 1 error-position) 
result) ) 


)) 


The stack functions are described in Chapter 31. RETEVAL, described in 
Section 30.8, allows you to return from a stack frame with a value without actu- 
ally completing the computation that was to be performed by the function repre- 
sented at the stack frame. The purpose of much of the code in the above function 
is to define a list which actually computes the result to be returned from the 
frame. RETEVAL evaluates the list, places the value in the appropriate frame 
location, and returns to the caller. 
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The INTERLISP Editor 


INTERLISP provides an integrated editing facility that understands the charac- 
teristics of all the data structures that it supports. The editor can be invoked to 
edit any data structure either at the top-level READ-EVAL-PRINT loop or as a 
function invoked from another function within a user program. When called 
from within a program, an optional list of commands may be passed to the editor 
for execution. 

This editor is to be used to edit expressions from a terminal/keyboard com- 
bination. INTERLISP-D provides DEdit, a display editor, which works with the 
mouse and bit-mapped screens of the Xerox 11xx machines. The latter editor 
will be discussed in Volume 2. 

The Editor is just one of a number of programming utilities that IN- 
TERLISP provides to create an integrated programming environment. This 
chapter and the next discuss the Editor. Subsequent chapters discuss other pro- 
gramming utilities. 


19.1 INVOKING THE EDITOR 


The Editor may be used to edit function definitions, property lists, variable val- 
ues, and arbitrary expressions. It may be invoked from either the top level 
READ-EVAL-PRINT loop or from within a user program. When called from 
the top level, it seeks commands from the input file T corresponding to the user’s 
terminal. When called from a user’s program, it may be passed an optional list 
of commands for execution which it performs and then returns. The Editor is 
invoked by different functions for the modes associated with specific data struc- 
tures. 


19.1.1 Function Editing 


You may edit a function definition by executing EDITF, which takes the follow- 
ing form 
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Function: EDITF 
EDITFNS 
# Arguments: 1-N 
Arguments: 1) a function name, FN 
2) zero or more commands, COMMAND[1] ... 
COMMAND [N] 
Value: The name of the function (EDITF) 


or NIL (EDITFNS). 


EDITF is an NLAMBDA, nospread function. You must provide a function 
name as the first argument. Optionally, you may pass it a sequence of com- 
mands to be executed. EDITF returns the name of the function that it has 
edited, if successful. 

When EDITF is called, it must check several cases before editing the func- 
tion. 


The First Argument is an Expression 
The first argument is an EXPR. EDITF calls EDITE (see below) to edit the 
definition using the following statement: 


(PUTD name 
(EDITE 
(GETD 'fn) 
(LIST 'command[1] ... 'command[N]) 
‘fn 
'FNS) ) 


Note: PUTD and GETD are described in Sections 8.3 and 8.4, respectively. 
NAME may be an EXPR because it is broken or advised. Thus, several sub- 
cases must be considered: 


1. If NAME really is an EXPR, editing the broken or advised function will 
affect the original definition. However, the structure of the function defi- 
nition is changed. You are notified by a warning message so that you may 
position yourself properly before issuing editing commands. 


<— (DEFINEQ 
(trash (x) 
(RPLACA x NIL))) 
(TRASH) 


«(BREAK trash) 
(TRASH) 
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<(EDITF trash) 
Note: you are editing a broken definition. 
EDIT 
*PP 
(LAMBDA (X) 
(BREAK1 
(PROGN (RPLACA X NIL)) 
T TRASH NIL)) 


2. If NAME is not an EXPR and has no EXPR property, the File Package 
looks to see if it ““knows’’ where NAME is contained (e.g., on any noticed 
file). If it does, the EXPR definition of NAME is loaded onto its property 
list under the property EXPR. Editing continues as is in (2) below. If the 
File Package cannot find the source definition, a warning is printed, and 
editing proceeds. The latter case is possible when you advise compiled 
code, because you may want to edit the advice. 

3. If NAME is not an EXPR, but it does have an EXPR property, NAME is 
unbroken or unadvised (only with your approval, since you may want to 
edit the advice) and proceeds as in (2). 


The First Argument has an EXPR Property 
If the first argument is not an expression, it may have an EXPR property (see 
Section 8.1). EDITF prints PROP and executes: 


(EDITE 
(GETPROP 'fn 'EXPR) 
(LIST 'command[1] ... 'command[N]) 
‘fn 
'PROP) 


When EDITE completes, several possibilities may have occurred: 


1. If no changes were made, EDITE responds with the message ‘‘“NOT 
CHANGED, SO NOT UNSAVED” 


«-(SETQ trash NIL) 
NIL 


«(PUTPROP trash 

'EXPR 

'(LAMBDA (x) (RPLACA x NIL))) 
TRASH 


<(EDITF trash) 
PROP 
EDIT 
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¥ok 
Not changed, so not unsaved. 


If changes were made, and DNAMEFLG has the value PROP, EDITE 
responds with the message ‘“‘CHANGED, BUT NOT UNSAVED” 


—-DNAMEFLG 
PROP 


<(EDITF trash) 

PROP 

EDIT 

*PP 

(LAMBDA (x) (RPLACA x NIL)) 
¥3 P 

(RPLACA x NIL) 

*(REPLACE 1 WITH RPLACD) 
*OK 

Changed, but not unsaved. 


Otherwise, EDITE responds with the message “‘UNSAVED” and exe- 
cutes UNSAVEDFF (see Section 17.5.7). 

UNSAVEDFF restores the definition of the function from its prop- 
erty list. The effect of the invocation of EDITE is to put the modified 
definition on the property list of the first argument (evaluating to a literal 
atom) under the property PROP. Then, UNSAVEDEF copies the defini- 
tion back to the EXPR property. 

Note: INTERLISP/370 unsaves in any case. 


The First Argument (as a Literal Atom) is Contained in some File Known to 
the File Package 

The first argument is neither an expression nor does it have an EXPR property 
value. When evaluated, it resolves to a literal atom. The File Package deter- 
mines if the atom is contained in a file that it knows. If so, it loads the EXPR 
definition of the atom from the file using LOADDEF (see Section 17.5.8). It 
then operates like (2) above. 


The First Argument has a Definition 
The first argument is neither an expression nor has an EXPR property value, but 
it does have a definition. EDITF prints (name) NOT EDITABLE. 


«+(SETQ trash '(RPLACA x NIL)) 
(RPLACA x NIL) 
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<—(EDITF trash) 
trash not editable. 


You should use EDITV instead. 


The First Argument’s Value is a List 
If the first argument’s value is a list, EDITF assumes that you meant to call 
EDITV. It displays ““=EDITV” and invokes EDITV for you: 


+(SETQ sentence '(now is the time for all good men)) 
(NOW IS THE TIME FOR ALL GOOD MEN) 


«(EDITF sentence) 

=EDITV 

EDIT 

*P 

(NOW IS THE TIME FOR ALL GOOD MEN) 


Alternatively, if NAME has a non-NIL property list, the editor assumes you 
meant to call EDITP. It displays the message ‘‘=EDITP”’ and invokes it for 
you. For example, 


<-(PUTPROP sentence 

"value 

'(now is the time for all good men)) 
(NOW IS THE TIME FOR ALL GOOD MEN) 


<-(EDITF sentence) 

=EDITP 

EDIT 

*P 

(NOW IS THE TIME FOR ALL GOOD MEN) 


The editor invokes EDITP only if the variable value is NIL; otherwise, 
EDITV takes precedence. 


None of the Above 
If none of the above cases pertains, EDITF attempts to correct the spelling of the 
name using the spelling list USERWORDS (see Section 22.7.2). If successful, it 
begins anew at (1). 

Whenever a function has been successfully edited, EDITE inserts a time 
stamp in the form of a comment (* xxx (date)) in the function definition. XXX 
are the user’s initials (see INITIALS). If a time stamp already exists, only the 
date in the comment will be changed. 
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+-(SETQ INITIALSLST (CONS 'kaisler 'shk)) 
(KAISLER . SHK) 


+-(DEFINEQ (trash (x) (RPLACA x NIL))) 


(TRASH) 

<—(SETQ **COMMENTFLG** T) 
T 

<(EDITF trash) 

¥3 P 


(RPLACA x NIL) 
*(REPLACE 1 WITH SETQ) 
*OK 

(TRASH) 


«(PP trash) 
(LAMBDA (x) 
(SETQ x NIL)) 


Often, we want to perform the same set of commands on several functions. 
The Editor provides the function EDITFNS to accomplish this task. In this case, 
the value of the first argument is an S-expression that evaluates to a list of one or 
more function names. EDITFNS calls EDITF on each function with the optional 
list of commands, if any. EDITFNS always returns NIL. 

FN may be an atom. If its value is not a list, but is a noticed file name, 
FILEFNSLST (see Section 17.7.3) is invoked to return a list of functions to be 
edited. FILEFNSLST extracts the functions from the FNS command associated 
with the File Package commands. 

When EDITENS executes, each call to EDITF will be ERRORSET pro- 
tected. Thus, it continues to process the list of functions even if one element of 
the list causes an error. This might occur if one of the editing commands fails for 
an element or an element is not a function. 


19.1.2 Value Editing 


You edit the value of a variable by executing the function EDITV. EDITV, like 
EDITF, takes the following form 


Function: EDITV 
# Arguments: 1-N 
Arguments: 1) a variable name, NAME 
2-N) editor commands, COMMAND[1] ... 
COMMAND [N] 


Value: The name of the variable. 
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EDITV is an NLAMBDA, nospread function. 

Usually, EDITV is called with a single atom as its argument. It may have 
one or more optional arguments which are Editor commands to be performed 
upon the variable’s value. The editor checks several different cases: 


1. If NAME is an atom and has the value NOBIND, the Editor determines 
if it is the name of a function. If so, it assumes you meant to call EDITF, 
displays the message ““=EDITF”’, and calls EDITF with the name of the 
function. 


“trash 
U.B.A. 


<(EDITV trash) 

=EDITF 

EDIT 

*P 

(LAMBDA (X) (RPLACA X NIL)) 


Note that TRASH may not have a value in its value cell, but may 
have a definition in its function definition cell. 


2. If NAME is an atom and has a value, EDITV allows you to edit the value: 


<(SETQ trash.flag 'don't) 
"DON'T 


<(EDITV trash. flag) 
DON'T NOT EDITABLE. 


because an atomic value cannot be changed, but 


<-(SETQ phrase '(don't rain on my parade) ) 
(DON'T RAIN ON MY PARADE) 


«-(EDITV phrase) 

EDIT 

*P 

(DON'T RAIN ON MY PARADE) 
*(REPLACE RAIN WITH SNOW) 
*P 

(DON'T SNOW ON MY PARADE) 
*OK 

(PHRASE) 


phrase 
(DON'T SNOW ON MY PARADE) 
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3. If the value of NAME is a list, EDITV evaluates the list. It invokes 
EDITE (see below) on the result: 


—(SETQ attributes 
(LIST 
(LIST 'boy (LIST 'male 'young)) 
(LIST 'girl (LIST 'female 'young)))) 
((boy (male young))(girl (female young) ) ) 


*+-(EDITV (CADR (ASSOC 'boy attributes) )) 
EDIT 

*P 

(MALE YOUNG) 


4. Otherwise, EDITV attempts to correct the spelling of the variable name 
if DWIMFLG is T (see Section 22.2.1). To do so, it uses the list 
USERWORDS (see Section 22.7.2). EDITV repeats from the first case, 
if successful. 

If the variable has the value NIL, no spelling correction will be at- 
tempted because the variable has a value. However, an error results be- 
cause the value is not a list and, therefore, not editable. 

EDITV returns the name of the variable whose value it has edited. 


19.1.3 Property List Editing 


You may edit the property list of an atom by executing EDITP, which takes the 
form 


Function: EDITP 
# Arguments: 1-N 
Arguments: 1) an atom, ATM 
2-N) editor commands, COMMAND[1] ... 
COMMAND [NJ 
Value: The name of the atom. 


EDITP is an NLAMBDA, nospread function. 

If the atom does not have a property list, EDITP attempts spelling correc- 
tion using USERWORDS (see Section 22.7.2). Note that here the presumption 
is that you really want to edit a property list and that it’s the atom name that is 
probably wrong. 

EDITP calls EDITE with the property list of the atom, the atom name, and 
TYPE equal to PROPLIST. When EDITE returns, EDITP establishes the value 
of the atom’s property list via SETPROPLIST as the list returned by EDITE. 

EDITP returns the name of the atom whose property list it has edited. 
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A Definition for EDITP 
We might define EDITP as follows: 


(DEFINEQ 
(EDITP 
(NLAMBDA (editp-arguments) 
(* 
Make EDITP-ARGUMENTS a list so it can be 
dissected. Note that its value may be a single 
atom. 
) 
(AND 
editp-arguments 
(NLISTP editp-arguments) 
(SETQ editp-arguments (LIST editp-arguments) ) ) 
(PROG (name property-list) 
(SETQ name (CAR editp-arguments) 
(COND 
((NOT (ATOM name) ) 
(* 
If the argument is not an atom, 
just return. 


) 

(RETURN NIL) )) 
(SETQ property-list (GETPROPLIST name) ) 
(* 


Now, if the property list is NIL, assume 
that the user misspelled the atom's name. 
Attempt to correct it if DWIM is enabled. 


(AND DWIMFLG 
(NLISTP property-list) 
(SETQ name 
(OR 
(MISSPELLED? name NIL USERWORDS) 
name) ) 
(SETQ property-list (GETPROPLIST name) ) ) 
(* 
Now, we probably have an atom with a 
property list. If we don't, because the 
atom really doesn't have one, then EDITE 
returns NIL which is just put back in 
place. 


(SETPROPLIST name 
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(EDITE property-list 
(CDR editp-arguments) 
name 
'PROPLIST) ) 
(RETURN name) ) 
)) 


19.1.4 Editing an Expression 


EDITE is the general-purpose expression editor. EDITE has the following ge- 
neric format: 


Function: EDITE 
# Arguments: 5 


Arguments: 1) an expression, EXPRESSION 
2) an optional command list, COMMANDS 
3) an atom, ATM 
4) an argument type, TYPE 
5) a function invoked if the expression is 
modified, IFCHANGEDFN 


Value: The expression (possibly modified). 


EDITE invokes EDITL, the INTERLISP Editor, with EXPRESSION as its 
argument. It generates an error if EXPRESSION is not a list. The optional com- 
mand list is a list of zero or more commands that will be applied to the expres- 
sion. 

ATM is the name of the object with which the expression is associated. 
TYPE gives the nature of the association; it is optional. 

IFCHANGEDEN is a function that is applied to the expression if it was 
changed. The format for invoking IFCHANGEDEN is 


(<IFCHANGEDFN) <atom) <expression) <type) <flag)) 


A Definition for EDITE 
We might define EDITE as follows: 


(DEFINEQ 
(EDITE (expression commands name type ifchangedfn) 
(PROG (an-expression) 
(COND 
((NLISTP expression) 
(* 


If EXPRESSION is not a 
list, we cannot edit it. 
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(PRIN1 expression) 

(PRIN1 " NOT EDITABLE") 

(TERPRI) 

(RETURN expression) ) ) 
(SETQ an-expression 


(LAST 
(EDITL (LIST expression) 
commands 
name) ) ) 


(COND 
((NOT (EQUAL expression an- 
expression) ) 
(* 
If the expression was 
really modified, then apply 
IFCHANGEDFN to it. 
) 
(RETURN 
(AND ifchangedfn 
(APPLY* ifchangedfn 
name 
an-expression 
type 
flag))))) 
(HELP expression 
"NOT A LIST"') 
(RETURN NIL)) 
)) 


19.2 EDITL: THE INTERLISP EDITOR 
EDITL is the INTERLISP Editor. The generic format for invoking EDITL is 


Function: EDITL 
# Arguments: 5 


Arguments: 1) a list to be edited, LST 
2) an optional list of commands, COMMANDS 
3) an atom, ATM 
4) a message, MESSAGE 
5) an atom whose value reflects the edit 
changes, EDITCHANGES 


Value: The value of the first argument at the 
time EDITL is exited. 
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EDITL edits the list that is its first argument as follows: 


1. If COMMANDS is non-NIL, EDITL applies the list of commands to its 
first argument until an exit condition is encountered. 

2. If COMMANDS is NIL, EDITL prints “EDIT” and a prompt character 
on the terminal and waits for the user to enter commands to edit the first 
argument. 


In interactive editing, an exit will occur only when one of the commands— 
OK, STOP, or SAVE—is recognized. 

All input to the Editor is affected by the current values in EDITRDTBL. 

MESSAGE is typed on the terminal if it is non-NIL. It will not be displayed 
if COMMANDS is non-NIL, i.e., it serves as an alternative message to the user 
in lieu of “EDIT”’’. 

ATM is optional. It refers to the object that is being edited. Its type depends 
on the calling function. Note that the SAVE command uses the property list of 
the atom to save the current state of the edit. Of course, nothing will be saved if 
the atom name is NIL. 

EDITCHANGES is used to store a list of changes to the first argument. 

An alternative form, EDITLO, operates like EDITL except it does not re- 
bind or initialize the Editor’s state variables. 


19.3 EDITOR FUNCTIONS 


The Editor relies on a number of ‘‘workhorse”’ functions to perform its opera- 
tions. These functions may also be called from your programs to perform the 
basic editing operations. 


19.3.1 Finding a Pattern 
EDIT4E is the basic pattern matching routine of the Editor. It takes the form 


Function: EDIT4E 
# Arguments: 2 
Arguments: 1) a pattern, PATTERN 
2) an expression, EXPRESSION 
Value: T, if PATTERN matches EXPRESSION. 


EDIT4E matches PATTERN according to the definition provided in Sec- 
tion 19.4.4. 

Before each search operation, the Editor scans the entire pattern for atoms 
or strings containing the character sequence $s (or (ESC)s). Each atom or 
string is replaced by a list of the form ($ ...). A similar approach is taken for 
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atoms or strings ending in $$s (or (ESC) <{ESC)s). These patterns are detected 
by taking the CAR of PATTERN. If you want to detect these from your pro- 
gram, you must convert your expressions to this form. 

EDITFPAT makes a copy of its argument, PATTERN, with all atoms or 
strings containing $s (or (ESC)s) converted to the form expected by EDIT4E. 


Implementing the Find Command 
You may search for a pattern using the Editor’s Find command using EDIT- 
FINDP, which takes the form 


Function: EDITFINDP 
# Arguments: 3 


Arguments: 1) an expression, EXPRESSION 
2) a pattern, PATTERN 
3) a flag, FLAG 


Value: T, if the PATTERN is found in EXPRESSION 
because F PATTERN would succeed; NIL, 
otherwise. 


EDITFINDP executes the Editor’s Find command as a pure predicate. If 
FLAG is NIL, EDITFPAT is invoked to convert PATTERN to the form ex- 
pected by EDIT4E. Thus, you may call EDITFPAT once, and EDITFINDP sev- 
eral times if you are looking for several different expressions. 


19.3.2 Substituting in an Expression 


The Editor’s Replace command may be executed directly using ESUBST, which 
takes the form 


Function: ESUBST 
# Arguments: 5 


Arguments: 1) a new expression, NEW 
2) an old expression, OLD 
3) an expression, EXPRESSION 
4) an error flag, ERRORFLAG 
5) a character flag, CHARFLAG 


Value: The modified EXPRESSION. 


ESUBST performs the Editor’s Replace command that is equivalent to (R 
<old) <new)). EXPRESSION is assumed to be the current expression. If OLD 
is not found in EXPRESSION, an error is generated. If ERRORFLAG is T, an 
error message of the form ‘“‘OLD ?”’ will be printed. 
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If CHARFLAG is T and no forms like $s (or (ESC)s) are specified in NEW 
or OLD, ESUBST operates like (RC (old) <new)). 
ESUBST is always undoable. 


19.3.3 Changing Names 


CHANGENAME is used to change the names of objects in a function. It is pri- 
marily used by the Break and Advising Packages to change the name of a func- 
tion within another function. It takes the form 


Function: CHANGENAME 
# Arguments: 3 


Arguments: 1) a function, FN 
2) the old name, FROM 
3) the new name, TO 


Value: Either FN or NIL. 


CHANGENAME replaces all occurrences of FROM by TO in the specified 
function. CHANGENAME succeeds whether FN has a symbolic form, e.g., it is 
an EXPR, or it is compiled. CHANGENAME returns FN if at least one instance 
of FROM is found in the definition. 


19.3.4 Searching Files 


EDITCALLERS provides a mechanism for rapidly searching a single file or set 
of files, whether they are loaded or noticed or not. It takes the form 


Function: EDITCALLERS 
# Arguments: 3 


Arguments: 1) a list of atoms, ATOMS 
2) a list of files, FILES 
3) a list of commands, COMS 


Value: The list of files. 


EDITCALLERS uses FFILEPOS to search each file in FILES for occur- 
rences of the atoms in ATOMS. For each occurrence that is found, EDITE is 
invoked to apply the commands in COMS to the detected atoms. COMS may be 
NIL, whence (EXAM . <atoms)) is used. Both ATOMS and FILES may be sin- 
gle atoms. If FILES is NIL, FILELST is used as the default list of files. 

EDITCALLERS prints the name of each file that it searches. When it finds 
an occurrence of an atom in ATOMS, it prints either the name of the function 
containing the atom or the byte position of the atom in the file. If a file map is 
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available, EDITCALLERS uses it to speed up the search. EDITCALLERS al- 
ways calls the Editor. 

An alternative form, FINDCALLERS, which takes the arguments ATOMS 
and FILES, merely performs the search, but never calls the Editor. 


19.3.5 Tracing Editor Macros 
EDITRACEEN is used to help you debug edit macros. It takes the form 


Function: EDITRACEFN 

# Arguments: 1 

Arguments: 1) a command, COMMAND 

Value: The value of the trace or break. 


EDITRACEEN is initially NIL. If you set it to T, then EDITRACEFN will 
be invoked whenever a command not typed by you is about to be executed. The 
command may be an edit macro or a valid editor command. The command is 
passed to EDITRACEFN as its argument. You may define EDITRACEFN to 
handle the command as you see fit. 

If EDITRACEEN is set to TRACE, the name of the command and the cur- 
rent expression are printed. If EDITRACEFN is BREAK, the same information 
is printed and the Editor enters the Break Package. In the Break Package, you 
may examine the state of the Editor. 


19.4 EDITOR CONCEPTS 


Editor commands can be divided into a basic set that are easy to use and an 
advanced set that provide substantially more power and flexibility to the experi- 
enced user. To understand how the Editor works, it is necessary to understand 
the model for editing that the editor works with. This section describes these 
concepts. 


19.4.1 The Concept of Currency 


The INTERLISP editor works on list structures. As you know, lists are bounded 
by matched pairs of parentheses. Within each pair of matching parentheses, 
multiple lists and atoms—the elements of a list—may exist. The editor works 
within a matching pair of parentheses on one of the elements. 

Consider the following definition for a function: 


((ZEROP a) x) 
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(T 
(MINUS x)))) 


The top-level elements of this list structure are LAMBDA, (x), and (COND 
& &). The latter two elements are sublists having further structure. The &’s 
mean that there is yet greater complexity in a sublist. 

Using normal list processing terminology, sublists always have a level that is 
one greater than the level in which they are contained. Thus, the level of x in (x) 
is 2 where we count the top level as 1. Correspondingly, the level of MINUS is 4 
since it is located in the sublist of a sublist of a sublist. 

The editor works, usually, on one element of a list at a time. In order to 
access the elements of a sublist, we must descend into the sublist. To descend in 
to the sublist given by (COND & &), we must specify its element number to the 
editor (see Section 19.5.2). When we do so, the elements of that sublist become 
visible to us and the editor can manipulate them. 

In order to keep track of where it is in a list structure, the editor maintains 
an edit chain. This is merely a list structure on which is pushed the current ex- 
pression when the editor descends into one of its elements. 


19.4.2 The Print Level 


The Editor adheres to the print-level specification established by the system vari- 
able PRINTLEVEL. The Editor assumes an initial print level of (2 . 20). 


19.4.3 Multiple Commands per Line 


You may combine multiple commands per type-in line. The Editor will execute 
each command in turn. However, an error in any command will cause the termi- 
nation of the command sequence. 


19.4.4 Pattern Specifications for Searching 


All of the Editor commands that search use the same pattern matching routine. 
A pattern matches with an expression in the current expression if its satisfies any 
of the following conditions: 


. If the (pattern) is EQ to the expression. 

. If the <pattern) is the atom &. 

. If the {pattern} is a number and EQP to the expression. 
. If the (pattern) is a string and 


> WS No = 


(STREQUAL <pattern) <expression) ) 


is true. 
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5. If (CAR pattern) is the atom *ANY* and (CDR (pattern)) is itself a 
list of patterns, one of which matches the expression. 

6. If (pattern) is a literal atom or string containing one or more ${s) (e.g., 
{ESC)<s)) where each $ can match an indefinite (including 0) number 
of contiguous characters in the atom or string. 

7. If <pattern) is a literal atom or string ending in two (ESC)s, the <pat- 
tern) matches with an atom or string that is close to (pattern), in the 
same sense that the spelling corrector uses. 

8. If (CAR <pattern)) is the atom -- (e.g., two dashes), < pattern) matches 
the expression if (CDR <pattern)) matches with some tail of the expres- 
sion. If (CDR <pattern)) is NIL, then <pattern) matches any tail of the 
expression. 

9. If (CDR <pattern)) is the atom == (e.g., two equal signs), the ¢ pat- 
tern) matches the expression if and only if (CDR < pattern) is EQ to the 
expression. 

10. If (CADR (pattern) is the atom .. (e.g., two periods), < pattern) 
matches the expression if (CAR <pattern)) matches (CAR <expres- 
sion)), and (CDDR (pattern)) is contained within the expression. 

11. Otherwise, if the expression is a list, (pattern) matches the expression 
if (CAR <pattern)) matches (CAR <expression)) and (CDR ¢ pattern )) 
matches (CDR ¢expression)). 


The significance of these rules is described in more detail in the IRM. 


19.5 BASIC EDITOR COMMANDS 


This section will discuss the basic editor commands that will allow an unsophisti- 
cated user to “get started” with the editor. 


19.5.1 Printing the Current Expression 


You may print the current expression by executing the command P. If the cur- 
rent expression is the top level, then we would see 


*P 
(LAMBDA (a 1) (COND & & &)) 


where the & indicates that a sublist resides here. 

The Editor assumes an initial print level of (2 . 20), which means that sub- 
lists of sublists will be printed [i.e., (a 1)] and the tails of long lists will be abbrevi- 
ated as --. 

If you wish to see the entire expression to be edited, you may issue the com- 
mand ?, which forces the Editor to assume a print level of 1000. Thus, we have 
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*? 


(LAMBDA (a 1) (COND ((NULL 1) NIL) ((EQUAL (CAR 1) a) T) (T 
(MEMBER a (CDR 1))))) 


Note that the Editor does not observe any specific demarcations when it 
prints an expression in this manner. 


To prettyprint an expression in a more legible format, you may use the com- 
mand PP: 


¥PP 
(LAMBDA (a 1) 
(COND 
((NULL 1) NIL) 
((EQUAL (CAR 1) a) T) 
(T (MEMBER a (CDR 1))))) 


19.5.2 Descending a Level 


A positive integer directs the Editor to descend into the corresponding element 
of the current expression. If the element is an atom, the Editor prints an error 
indication consisting of the level number followed by a ?. 


*2 

(a 1) "the second element’ 

¥1 

we "cannot descend into an atom!’ 


Note that the current expression is never changed when a command fails, so 


*P 
(a 1) 


A negative integer forces the Editor to count backward from the end of the 
‘current expression to select the element into which to descend. 


¥-2 

(a 1) "again, the second element"' 

¥-3 

-3 ? "cannot exceed number of elements" 


Note that whenever we descend into an element, the current expression is 
always added to the edit chain. 
19.5.3 Ascending the Edit Chain 


To ascend the edit chain, you may issue the command 0. 0 operates by removing 
the last link of the edit chain and making it the current expression. 
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*P 

(NULL 1) "assume we are at the 4th level" 
*0 

(& NIL) "to the 3rd level" 

*0 

(COND & & &) "to the 2nd level" 


Note that 0 ascends one level each time that it is executed. If we are already 
at the top level of the list structure, 0 will cause an error because the Editor 
cannot remove any more links from the edit chain, i.e., the edit chain must al- 
ways be anchored by the top level of the list structure. 

In a particularly complex list structure, you may forget at what level of the 
list you currently reside. To “‘pop”’ up to the top level, you may execute the ft (up- 
arrow) command to force the editor to ascend to the top-most level. For exam- 
ple, 


*P 

(CDR 1) 

¥f (up-arrow) 

(LAMBDA (a 1) (COND & & &)) 


If you are already at the top-most level of the list structure, the (up-arrow) 
command has no effect. 


19.5.4 Modifying the List Structure 


The structure modification commands always work on the current structure. 
The general form of the structure modification command is (# (expression-list) ) 
where the <expression-list ) may be empty. The # may be either positive or nega- 
tive and determines the element in the current expression that is to be modified. 
To delete an element from the current expression, you may issue the com- 
mand (#) where # is the index of the corresponding element to be deleted. 


xP 
(COND (& NIL) (& T) (T &)) 
*(2) 

xP 

(COND (& T) (T &)) 


where the element (& NIL) has been deleted. Note that the new structure is not 
automatically printed after modification. 
Structure modification performed by the Editor is destructive, i.e., it physi- 
cally modifies the list structure using the functions RPLACA and RPLACD. 
To replace an element with one or more new elements, you may issue the 
command (# e[1] ... e[N]): 
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¥P 

(& NIL) 

*(2 T) 

*P 

(& T) "NIL is replaced by T" 


To insert one or more new elements before a given element, you may issue 


the command (-# e[1] ... e[N]). The sign of the number indicates that an inser- 
tion is to take place. 


¥P 

(COND & & &) 

*(-2 ((NULL a) NIL)) 
*P 

(COND & & & &) 


where a complex expression has been inserted before the second element. 

Note that all three commands execute with respect to the Nth element from 
the beginning of the current expression. There is no way to specify insertion or 
deletion from the end of the current expression. Nor can we specify insertion 
after a given element. This is rather tedious and may cause you some difficulty at 
first. 


19.5.5 Adding Elements to the End of the Current Expression 


Because we cannot insert after an element, we cannot put something at the end 
of the list using structure modification commands described in Section 19.5.4. 

To add elements to the end of the current expression, you may use the N com- 
mand. The N command NCONCs the elements provided to the end of the cur- 
rent expression. 


*P 

(LAMBDA (a 1) (COND & & &)) 
*3 P 

(COND (& NIL) (& t) (T &)) 
*(4) 

¥(N (T (EQUAL a (CADR 1)))) 
*4 P 

(T (EQUAL a (CADR 1))) 


Note that the N command performs an RPLACD on the last CDR of the 
current expression in order to patch in the new expression as the last element of 
the current expression. 
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19.5.6 Finding an Element 


One way to determine where to modify a structure is to perform a sequence of 
recursive descents into the structure. For small structures, this may be quite 
efficient and easy, particularly when the entire structure is composed of no more 
than a few lines of code. More than this requires substantial effort on your part 
to keep track of where you are. 

The Find command allows you to search a structure for a pattern. The for- 
mat of the Find command is 


*¥F (pattern) 


where <pattern) is the thing to be looked for in the list structure. 

When the Find command is executed, the Editor begins searching at the 
current level for the pattern. If it does not find it at the current level, it ascends 
one level (via an implied UP) and renews the search. However, the search pro- 
ceeds only in the forward direction. Thus, when the Editor ascends a level, it 
searches only those elements following the element at which the search began. 

If the search succeeds, the Editor sets the current expression to the structure 
element where the pattern is found. If the search fails, the current expression is 
not changed and an error message is displayed. 

Consider the following example: 


*P 
(LAMBDA (A L) (COND & & &)) 
¥3 P 
(COND (& NIL) (& T) (T &)) 
*2 P 
((NULL L) NIL) 
*F COND 
COND ? "look for a COND" 


The search failed to find a COND either in the current expression or any 
expressions following it in the structure. Note that a COND appears earlier in 
the structure but the Find command does not backtrack to locate it. To search 
from the previous level, we might have issued the command 


*0 F COND P 
whence the result would be 


(COND (& NIL) (& T) (T &)) 
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19.5.7 Replacing an Element 


In Section 19.5.4, we saw that we could replace an element of a structure by 
descending to that element and specifying a new element in its entirety. If we 
want to replace one atom of an element, this may become rather tedious. 

The Replace command allows us to locate an atom or subexpression of the 
current expression and substitute a new atom or expression for it. Consider the 
following example: 


*P 
(LAMBDA (A L) (COND & & &)) 
*¥3 P 
(COND (& NIL) (& T) (T &)) 
*(R EQ EQUAL) 
¥PP 
(LAMBDA (A L) 
(COND 
((NULL L) NIL) 
((EQUAL (CAR L) A) T) 
(T (MEMBER A (CDR L))))) 


The Replace command replaces all occurrences of the first argument by the 
second argument in the current expression. In this case, there was only one oc- 
currence for which the substitution was made. 

The Replace command requires that there be at least one occurrence where 
substitution takes place; otherwise, an error occurs. 


19.5.8 Exiting the Editor 


When you complete the editing of a structure, you may exit the editor by issuing 
the OKay command. OK saves the edited result in the proper place according to 
how it was invoked. 


19.6 AN EDITOR COMMAND ENCYCLOPEDIA 


The INTERLISP Editor provides a rich, powerful, flexible set of commands for 
manipulating list structures. Beyond the brief introduction given in Section 
19.5, it is difficult to instruct a user in the various Editor commands. We have 
found the best method is to wade in and try the various commands. You will feel 
comfortable with some but less so with others. Eventually, you will build a reper- 
toire of commands that you will use frequently. When you become “‘stuck,’’ be 
assured the Editor probably has a command for what you want to do, but you 
will have to look it up. 

In this spirit, this section presents an encyclopedia of Editor commands. 
The following table depicts the correspondence between the command, its func- 
tion, and the section in which it appears. 


EMBED 
EVAL 
EXAM 
EXTRACT 
F 

GETD 
GETVAL 
GET* 
GO 

IF 
INSERT 


JOINC 


LC 

LI 
LOWER 
LP 

M 
MAKE 


MAKEFN 
MARK 


MBD 
MOVE 
: 


NEGATE 
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Function 


After 

Before 

Below 

Backwards Find 

Both In 

Binding Variables 
Backup 

Both Out 

Capitalize 

(See REPLACE) 
Clispify 

Commands 

Deletion 

Dwimify 

Evaluate 

EMBEDding 

EVALuation 

EXAMine 

(See XTR) 

Finding an expression 
GETting a Definition 
GETting a VALue 
GETting a comment 
GOing to a PROG label 
Conditional Editing 
Inserting into an 
expression 

Joining Conditional 
expressions 

Lower Case 

Left Insert 

Lower Case 

LooPing 

Macro definition 
MAKE a parameter 
have a value 

MAKE a FunctioN 
MARKing and Restoring 
the edit chain 

(see EMBED) 

MOVE an expression 
Adding to the eNd of 
an expression 
NEGATEing an expression 


Section 
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NEX 


NIL 
NTH 
NX 

OK 
ORF 
ORIGINAL 
- ORR 

P 

PP 

PPx 
PRT 
PPV 

Q 

R 
RAISE 
RC 
REPACK 


REPLACE 
RI 

RO 

R1 

S 

SAVE 
SHOW 
SPLITC 
STOP 
SURROUND 
SW 

SWAP 
SWAPC 
TEST 
THRU 

TO 

Try: 
UNBLOCK 
UNDO 

UP 

XTR 

¥% 

<n), -<n) 
0 

2ND 
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Advancing to the NEXt 
expression 

NIL 

NTH Element 

(see NEX) 

OKay to exit 

(see F) 

ORIGINAL definition 
Execute one command 
Print expression 
(see P) 

(see P) 

(see P) 

(see P) 

(see EMBED) 

Replace 

RAISE to upper case 
(see R) 

Edit atom or string 
(REPACK) 

(see R) 

Right parenthesis in 
Right Parenthesis out 
(see R) 

Set literal atom 
(see OK) 

SHOW all instances 
SPLIT COND 

(see OK) 

(see EMBED) 

SWitch elements 

(see SW) 

(see SW) 

Add undo-block 
Location specification 
(see THRU) 

Call Editor 

(see TEST) 

UNDO last command 
Move UP the edit chain 
Extract 

Insert comment 


(see (n)) 
(see LC) 


19.6.37 


19.6.38 
19.6.39 


19.6.40 
19.6.41 


19.6.42 
19.6.43 


19.6.44 
19.6.45 


19.6.46 
19.6.47 
19.6.48 
19.6.49 
19.6.50 
19.6.51 
19.6.52 
19.6.53 
19.6.54 
19.6.55 
19.6.56 
19.6.57 
19.6.58 


19.6.69 
19.6.60 
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3RD (see LC) 

: (see DELETE) 
? (see P) 

\ (see MARK) 
+ (see UP) 

- (see MARK) 


Many of the Editor commands are treated as macros. Their definitions are 
maintained in the system variable EDITMACROS. You may discover these defi- 
nitions by executing 


«-(PRINTDEF EDITMACROS) 


We shall show the definition for each macro that appears on EDITMA- 
CROS. 


19.6.1 Inserting After the Current Expression 


The After command allows you to insert one or more S-expressions after the 
current S-expression. Its format is 


*(A e[1] ... e[n]) 
where the e[i] are S-expressions. Consider the following examples: 


«-(EDITE x) 
edit 
¥PP 
(COND 
((EQ A (CAR L)) 
(CDR L))) 

*(A ((EQ (CAR A) (CAR L)) (CADR L)) (T L)) 
can't -- at top 


because we are trying to add an S-expression after an entire current S-expres- 
sion. However, we really want to descend into the S-expression before editing: 


*2 P 
((EQ A &) (CDR L)) 
*(A ((EQ (CAR A) (CAR L)) (CADR L)) (T L)) 
*PP 
(((EQ A (CAR L)) 
(CDR L)) 
((EQ (CAR A) (CAR L)) 
(CADR L)) 
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(T L)) 
*0 P 
(COND (& &) (& &) (T L)) 


19.6.2 Inserting Before the Current Expression 


The Before command allows you to insert one or more S-expressions before the 
current expression. Its format is 


*(B e[1] ... ef[n]) 
where the e[i] are S-expressions. Consider the following examples: 


<-(EDITE x) 
edit 
*¥PP 
(COND 

((EQ A (CAR L)) 

(CDR L))) 

*(B ((AND (LISTP A) (EQ (CAR A) (CAR L))) (CADR L))) 
can't -- at top 


because we are trying to add an S-expression before an entire S-expression. We 
must descend into the S-expression as follows: 


*2 P 
((EQ (CAR A) (CAR L)) 
*(B ((AND (LISTP A) (EQ (CAR A) (CAR L))) (CADR L))) 
xP 
(((AND (LISTP A) 
(EQ (CAR A) 
(CAR L))) 
(CADR L)) 
((EQ A (CAR L)) 
(CDR L))) 


19.6.3 Locating a Pattern 


The BELOW command is used to locate current expression after a given pattern 
in a structure. Its format is 


*(BELOW <pattern) <n)) 


The Editor ascends the edit chain looking for a link specified by ¢ pattern). 
Ascension consists of performing Os (see Section 19.6.60) until a link is found 
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that matches (pattern). Then, the editor descends (n) links below that expres- 
sion. 
Consider the following example taken from the IRM: 


*¥PP 
(PROG NIL 
(COND 
((NULL (SETQ L (CDR L))) 
(COND 
(FLG (RETURN L)))) 
((NULL (CDR (MEMBER (CAR L) (CADR L))))))) 
*F CADR 
¥(BELOW COND) 
*P 
((NULL (CDR (MEMBER (CAR L)(CADR L))))) 


F CADR finds the S-expression (CADR L). Then, (BELOW COND) as- 
cends the edit chain four links: 


(MEMBER & &) 

(CDR &) 

(NULL &) 

(NULL &) "contains a COND" 


which is equivalent to 

*0 000 

The BELOW command forces the result shown above. Since <n) is NIL, 1 is 
assumed. 


BELOW locates a substructure by specifying an S-expression that it con- 
tains. 


19.6.4 Searching Backwards 


The Backwards Find command searches backwards from the current expression 
to locate an S-expression matching the pattern. Its format is 


*BF (pattern) 
Consider the following examples: 
*P 


(PROG NIL 
(SETQ X 
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(SETQ Y (LIST Z))) 


(COND 
((SETQ W (CAR X)) 
(CADR Z)))) 
*F LIST 
*BF SETQ 
*P 


(SETQ Y (LIST Z)) 


When BF ascends the edit chain to the previous link, it always begins its 
search at the end of the link. That is, it searches the list in reverse order. So, F 
LIST finds (LIST Z). Then, BF SETQ backs up to (SETQ Y (LIST Z)) which 
contains a SETQ and causes the search to terminate. 

BF continues ascending until the top of the edit chain is reached, whence it 
terminates with ?. 


*F CADR 


*BF RETURN 
? 


If the current expression is the top-level expression, the editor searches the 
entire expression in reverse order. 


*T "up arrow"! 
*BF CAR 

*P 

(CAR X) 


An alternative form, (BF <pattern) T), causes the current expression to be 
included in the search. : 


*F COND 

*(BF SETQ T) 

*P 

(SETQ W (CAR X)) 


because the search commences at the end of (COND &) which is the current 


expression. 
BF is constrained by the value of MAXLEVEL and UPFINDFLG. 


19.6.5 Inserting Balanced Parentheses 


The Both In command allows you to insert balanced parentheses around a se- 
quence of elements in the current expression. Its format is 


*(BI <n) <m)) 
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where (n) and <m) are the numeric indices of expressions within the current 
expression. 
Consider the following example: 


«-(EDITF is.zero) 


edit 
*PP 
(LAMBDA (NUM) 
(COND 
(ZEROP NUM 1) 
(T NUM) )) 
*F ZEROP 
*¥P 
(ZEROP NUM 1) 
*(BI 1 2) 
*P 


((ZEROP NUM) 1) 


BI inserts a left parenthesis before the (n)th element in the current expres- 
sion and a matching right parenthesis after the (m)th element. (m) must be 
greater than (n) and the (m)th element must be contained within the current 
expression. Otherwise, BI generates an error. 


*(BI 1 4) 
4? 

*(BI 2 1) 
(BI 21) ? 


An alternative form, (BI <n)), is equivalent to (BI <n) <n)). That is, it 
makes a list of the (n)th element. 


19.6.6 Binding Macro Variables 


The BIND command binds the dummy variables #1, #2, and #3, which are ini- 
tialized to NIL, and then executes a sequence of edit commands. Its format is 


*(BIND <commands) ) 


The IRM notes that you may define the SW command as 


(M 
(SW (N M) 
(BIND (NTH N) 
(S #1 1) 
MARK 0 


(NTH M) 
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(S #2 1) 
(I 1 #1) «+ (I 1 #2)))) 


The commands (S #1 1) and (S #2 1) set the macro variables #1 and #2 ap- 
propriately. 

The bindings for macro variables #1, #2, and #3 are effective only for the 
sequence of edit commands executed by BIND. 


19.6.7 Backing Up in the Current Expression 


A current expression may be embedded in a list. BacKup allows you to move to 
the previous expression in the edit chain, 


¥PP 

(COND 

((NULL X) 
(RETURN Y))) 

*F RETURN 
xP 

(RETURN Y) 
¥BK P 

(NULL X) 


where the list structure consists of (NULL X) (RETURN Y)). 
If the current expression is at the beginning of a list, an error will result. 
That is, BK does not ascend the edit chain. 


¥PP 

(COND 

((NULL X) 
(RETURN Y))) 

*F NULL 
xP 

(NULL X) 
*BK 
BK ? 


An alternative form, (BK <n)), allows you to specify the number of S-ex- 
pressions, (n) =) 1, to back up within the current list structure. If (n) would 
force BK to run off the front of the list, an error results and the edit chain is not 
changed. 


*PP 
(tyler polk johnson hayes taft arthur) 
*¥F taft 
*(BK 5) 
(BK 5) ? 
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A Definition for BK 


We might define a macro which backs up to a previous expression and prints it 
as follows: 


(BKP NIL 
(ORR (BK) 
(10) 
((E 
(PROGN 
(SETQQ COM BK) 
<5 (ERROR! ))))) 


19.6.8 Deleting Balanced Parentheses 


The Both Out command allows you to remove balanced parentheses from an 
element in an expression. Its format is 


*(BO <n)) 


where <n) identifies the Nth element in the expression. 
Consider the following example: 


*P 

((A B) C (D E F) G (HI)) 
*(BO 3) 

*P 


((A B) CD EF G (H1I)) 


If the Nth element is not a list or there are not N elements in the expression, 
an error is generated. 


*P 

((A B) C (D E F) G (H I)) 
*(BO 4) 

(BO 4) ? 

*(BO 6) 

(BO 6) ? 


19.6.9 Capitalization 


The CAPitalization command capitalizes an atom or a string. It RAISEs the 
characters in the element and then LOWERs all but the first character. If the 
atom or string is already capitalized, nothing happens. 
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*P 
IGNORECHARACTERCODES 
¥CAP 

*P 
Ignorecharactercodes 


CAP’s macro definition appears as 


(CAP NIL 
RAISE (I 1 (L-CASE (##1) T))) 


19.6.10 CLISPIFYing Expressions 


The CLISPIFY command translates the current expression to CLISP format 
(see Chapter 23). 


*P 
(COND 
((NULL x) 
(PROG (value) 
loop 
(COND 
((EQ (SETQ x (READ) 'STOP) 
(RETURN value) )) 
(PRINT (EVAL x)) 
(GO loop) ))) 
¥*CL 
*P 
(if (NULL x) 
then while x«-(READ) = 'STOP 
do (PRINT (EVAL x))) 


A Definition for CL 
CL has the following macro definition: 


(CL NIL 
(BIND 
(IF (NULL (CDR L)) 
(IF (MEMB (##1) LAMBDASPLST) 
((MARK #3) 3 UP) 
((E 
(PROGN 
(SETQQ COM CL) 
(PRINT 'can't) T T) 
(ERROR! )))) 
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NIL) 
(IF (TAILP (SETQ #1 (##)) 
##10 
(E 


(SETQ #2 L) T))) 
((I : (CLISPIFY #1 #2)) 
(LO 1)) 
((COMS 
(CONS ': (CLISPIFY #1 #2)) 
(AND (LISTP (##1) 1)) 
(IF #3 (( #3)) NIL))) 


19.6.11 Command Execution 


COMS takes one or more S-expressions as its arguments. It evaluates each S- 
expression in turn and then executes it as an Editor command. Its format is 


*(COMS expression[1] ... expression[N]) 


where each EXPRESSION|Ii] is an S-expression which, when evaluated, yields 
an Editor command. 

An alternative form, COMSQ, takes as its arguments one or more S-expres- 
sions which it executes as Editor commands (e.g., its arguments are Editor com- 
mands). Its format is 


*(COMSQ command[1] ... command[N]) 


where each COMMAND|i] is an Editor command. 

COMS and COMSQ may be used in conjunction to execute commands that 
are attached to an INTERLISP object that is being edited, perhaps as entries on 
its property list. Different properties may describe how to edit the data struc- 
ture. 


19.6.12 Deleting Expressions 


The DELETE command deletes the current expression on the edit chain: 


*P 

(COND 
(A (PRINT B)) 
(T (HELP) ) ) 

*F HELP 

*DELETE 

*P 

(T) 
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DELETE tries to delete the current expression by performing an UP and 
then (1). This works in all cases except where the current expression contains 
exactly one element, because you cannot delete something and leave an empty 
list. Then, DELETE performs, BK, UP, (2). 

When the next higher expression contains only one element, BK will not 
succeed. Then, DELETE performs (: NIL). That is, it replaces the higher ex- 
pression by NIL. 

DELETE might be defined as an edit macro as follows: 


(DELETE NIL 
(ORR (UP (1)) 
(BK UP (2)) 
(: NIL))) 


An alternative form, D, combines the actions of DELETE and P by deleting 
the current expression and printing the new current expression. It might be de- 
fined as 


(D NIL (:) 1 P) 


Another form, :, also deletes the current expression. 


19.6.13 DWIMIFYing Expressions 


The DWIMIFY command allows you to DWIMIFY the current expression (see 
Section 22.5). The process of DWIMIFYing is described in detail in Chapter 22. 
A macro definition for the DW command is 


(DW NIL 
(BIND 
(E 
(PROGN 
(SETQ #1 (##)) 
(AND 
(CDR L) 
(##!0 (E (SETQ #2 L) T))) 
(AND 
(SETQ #3 
(DWIMIFY #1 T (OR #2 
'NIL))) 
EDITCHANGES 
(RPLACA (CDR EDITCHANGES) T))) 
T) 


(IF (NLISTP #1) 
((I : #3) 
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(IF (LISTP #3) 
(1) 
NIL) ) 
NIL) )) 


You may disable DWIMIFYing in the Editor using the following command: 


(1DW NIL 
(RESETVAR CLISPRETRANFLG T DW)) 


19.6.14 Evaluating Input 


From the Editor, you may evaluate any S-expression. To do so, you must enter 
the Evaluate command followed by the expression to be evaluated. Note that E 
only works when typed in at your terminal. It takes the form 


*¥E (expression) 


where the expression is evaluated. For example, while editing, you may want to 
evaluate part of an expression, see what it produces, and force a break. Using E, 
you enter 


*(E (LOAD 'COMPLEX) ) 

{KAISLER) COMPLEX. .2 

FILE CREATED 30-Aug-84 20:44:36 
COMPLEXCOMS 


An alternative form is (E (expression) ). (expression) is evaluated and then 
E performs an EVAL (see below) on its result. The value is printed at your termi- 
nal. 


*(E (SETQ X '(IPLUS (SETQ X 1) (SETQ Y 4)))) 
(SETQ X '(IPLUS (SETQ X 1)(SETQ Y 4))) 


If you do not want the result to be printed at your terminal, you may use the 
form 


¥(E (SETQ X '(IPLUS (SETQ X 1) (SETQ Y 4))) T) 


which suppresses printing of the result of the expression, except during type-in 
mode. 

I have noticed that this command is particularly useful when you are editing 
broken functions because you may inspect the values of variables or subexpres- 
sions of the function from within the Break Package. 
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19.6.15 Embedding 


Embedding replaces the current expression with one containing it as a subex- 
pression. There are two forms to this command: 


*%(EMBED @ IN <expression)) 


where @ is some S-expression (possibly, an atom) which is to be inserted into the 
S-expression given by (expression). 


+-(EDITF ROUNDTO) 


edit 
*PP 
(LAMBDA (X Y) 
(TIMES (ROUNDED (QUOTIENT X Y) 
Y)) 
*(EMBED QUOTIENT IN PRINT) 
*PP 
(LAMBDA (X Y) 


(TIMES (ROUNDED (PRINT (QUOTIENT X Y)) Y))) 


EMBED locates the S-expression identified by @ via (LC . @). It then cre- 
ates a new S-expression with @ embedded via (MBD . expression). 
MBD is the command that performs embedding. It takes the form: 


*(MBD <expression1) ... <expressionN)) 


MBD substitutes the current expression for all instances of the atom & in 
each of the <expression[1]). The current expression is replaced by the result of 
that substitution via SUBST. MBD sets the edit chain to be the new current 
expression. 

Another alternative, Q, quotes the current expression by embedding a 
QUOTE in front of the expression. It takes the form 


*Q 
Q may be defined as an edit macro as follows: 


(Q NIL 
(MBD QUOTE) ) 


Another alternative form, SURROUND, performs the same function as 
EMBED but is easier understood. It takes the form 


*(SURROUND @ WITH . <expression)) 
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19.6.16 Evaluating an Expression 


You may evaluate the current expression in the edit chain by issuing the EVALu- 
ate command. It takes the form 


*EVAL 


You may use EVAL and NX to single-step a program through its symbolic 
definition. Assume we have the PROG form: 


¥E (SETQ CITIES (LIST 'WICHITA 'ALBANY 'BOISE 'SALEM)) 
¥PP 
(PROG (CITY) 
LOOP (SETQ CITY (CAR CITIES) ) 
(PRIN1 CITY) 
(TERPRI) 
(SETQ CITIES (CDR CITIES) ) 
(AND 
(NULL CITIES) 
(RETURN) ) 
(GO LOOP) ) 


The execution of the PROG would be handled by the following sequence of 
commands: 


*F SETQ 

*P 

(SETQ CITY (CAR CITIES) ) 
*EVAL 

WICHITA 

¥NX 

*P 

(PRIN1 CITY) 

*EVAL 

WIHCITAWICHITA 


A macro definition for EVAL is 


(EVAL NIL 
(ORR 
(E 
(LISPXEVAL (## (ORR UP1) NIL)) '*) 
((E 'EVAL?)))) 
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19.6.17 Examining an Expression 


EXAMine allows you to invoke the Editor on an expression from within the Edi- 
tor. Its form is 


*(EXAM . <expression) ) 


(expression ) is a pattern or list of patterns. The Editor will be invoked for every 
instance of the expression. Assuming we are in the PROG expression mentioned 
in Section 19.6.16, we have 


'*(EXAM . CITIES) 

(SETQ CITIES (CDR CITIES) ) 
tty: 

*P 

(SETQ CITIES (CDR CITIES) ) 
*OK 

(CDR CITIES) 

tty: 

*OK 

(NULL CITIES) 

tty: 

*OK 

done 

x 


where the Editor has stepped us through every instance where CITIES occurs in 
the remaining S-expressions from the current edit chain. At each instance, we 
can enter editing commands to modify that particular instance. 

We might define EXAM as a macro as follows: 


(EXAM X 
(F (*ANY* . X) T) 
(BIND (LPQ (MARK #1) 
(ORR (1 !0 P) NIL) 
(MARK #2) 
sh 
(MARK #3) 
(IF (EQ (##(\ #3)) 
(##(\ #2))) 
((\ #1)) 
NIL) 
(F (*ANY* . X) N))) 
(E 'done) ) 
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19.6.18 Finding an S-expression 


When editing a function or expression, you must be able to locate the expression 
within the function to be modified. The Find command and its variations search 
an expression for a given pattern. If the search is successful, the current expres- 
sion becomes the pattern sought. 

The basic form of the F command is 


*¥F (pattern) 
where < pattern) is to be sought in the function or expression that is being edited. 
If the pattern exists within the current expression, F does not proceed to search 
further, i.e., F initially executes 


(MEMBER <pattern) <current-expression) ) 


Consider the following examples (after the IRM): 


*PP 
(PROG NIL 

(SETQ ...) 
LOOP 

(COND 


MMOLE. oct) - 5.4 
((MEMBER ...)(GO LOOP1) 
(T (GO LOOP) )) 

LOOP1 (RETURN) ) 


¥1 
*F LOOP1 
*P 

. LOOP1) 


finds the first LOOP1 which is embedded within the COND because PROG is 
the current expression. The ... indicates that there is a part of the S-expression 
preceding the atom that was found. However, 


*0 P 
*F LOOP1 


finds the label LOOP1 within the PROG. 
You can find the next instance of a pattern by using the alternative form 


*F (pattern) N 
*(F (pattern) N) 
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This form does not perform the check against the current expression. 
You may determine if there is another instance of the pattern in the function 
or expression using the alternative form 


*¥F <pattern) T 
*(F <pattern) T) 


. This form looks for the pattern, but does not change the edit chain when it 
finds an instance of the pattern. It does not check the current expression. 
If there are multiple instances of a pattern in the function or expression, you 
can find the Nth instance using the alternative form 


*(F <pattern) <n)) 


where <n) is greater than or equal to 1. This form is equivalent to 


*(F (pattern) T) 
*¥(F (pattern) N) repeated N-1 times. 


If the pattern does not match N times, an error is generated and the edit 
chain remains unchanged. 


*F LOOP1 4 
LOOP1 ? 


The search algorithm used by F descends into lists to match its pattern. If 
you want to match only the top-level elements of the current expression, you may 
use the alternative form (differing from the basic form by enclosure within pa- 
rentheses) 


*(F <pattern)) 
*F <pattern) NIL 


Consider the following example: 


*P 
(PROG (...) 
(SETQ ... 
(COND 
(Coss) 
((.--)))) 
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CT coe¥)) 
*F COND 


will find the COND inside the SETQ because that form descends into lists. 
*(F COND) 

finds the second COND because it occurs at the top level of the PROG form. 

Finding Any Pattern 

An alternative form, ORF, searches for an expression that matches any one of 


the patterns given as its arguments. It takes the form 


*(ORF <patternl) ... <patternN)) 


19.6.19 Getting a Definition 


The GET Definition command expands the current expression in line if it is one 
of the following cases: 


1. If the CAR of the current expression is the name of a macro, the macro 
name is replaced by its current expansion. 

2. If the CAR of the current expression is a CLISP word, the current expres- 
sion is replaced by its translation. 


xP 
((if (NLISTP X) then (CAR X))) 
*1 

*GETD 

*PP 

(COND 

((LISTP X) 
(CAR X))) 


Note that the translation eliminated the double negative. 

3. If CAR of the current expression is a function name, the arguments are 
substituted into the body of the function definition and the result re- 
places the function invocation. 


<-(EDITF ROUNDTO) 
edit 

*PP 

(LAMBDA (X Y) 
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(TIMES (ROUNDED (QUOTIENT X Y) Y))) 
*3 2P 
(ROUNDED (QUOTIENT X Y) Y) 
*GETD 
*PP 
(TRUNCATE (PLUS (QUOTIENT X Y) 
(QUOTIENT (SIGN (QUOTIENT X Y)) 
2))) 


GETD must be able to access the symbolic definition of the function 
from memory or from a noticed file. 


4. If CAR of the current expression is LAMBDA, the arguments are substi- 
tuted into the body of the LAMBDA which replaces the LAMBDA ex- 
pression in the current expression. 


A macro definition for GETD is (from EDITMACROS) 


(GETD NIL 
UP 
(ORR 
((I 1 (OR 
(EDIT GETD (##1) 
(AND (CDR L) 


(EDITLO L '!0))) 
(ERROR! ) ) ) 
((E 'GETD?))) 
1) 


19.6.20 Getting a Value 


The GET VALue command replaces the current expression by its value after it 
has been evaluated. Note that evaluation may generate an error if the evaluation 
depends on the establishment of a certain environment. It takes the form 


*GETVAL 


The current expression in the edit chain is evaluated and the result replaces 
the expression that was evaluated. You cannot replace the top-level expression in 


the edit chain with its value. 
A macro definition for GETVAL is (from EDITMACROS) 


(GETVAL NIL 
UP 
(ORR 
((I 1 (EVAL (##1) '*))) 
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((E 'GETVAL?)) ) 
1) 


19.6.21 Getting a Comment 


GET* retrieves the full text of a comment if the current expression is a comment 
pointer (see Section 16.10). The comment pointer is replaced by the full text. 
A macro definition for GET* is (from EDITMACROS) 


(GET* NIL 
(BIND 
(IF (NEQ (SETQ #1 (GETCOMMENT (##) )) 
(##) ) 
((I : #1) 
1) 
NIL) )) 


19.6.22 Going to a PROG Label 
The GO command makes the current expression be an S-expression immedi- 
ately after the PROG label. It takes the form 

*(GO <label)) 


If there is no label in the edit chain having the given name, the Editor prints 
a warning and waits for a new command. 
A macro definition for GO is (from EDITMACROS) 


(GO (LAB) 
(ORR 
((< ((*ANY* PROG ASSEMBLE DPROG) 
--LAB )) 
F LAB (ORR 2 1) 
P) 
((E 
(PROGN 


(SETQQ COM LAB) 
(ERROR! )))))) 


19.6.23 Conditional Listing 


The IF command allows you to perform conditional editing. The general form is 


*(IF <expression)) 
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In this form, the Editor evaluates (expression). If the result is an error or 
NIL, the result of the command is an error. 

At the top level of the Editor, this form is not particularly useful. However, 
several editor commands use errors to force sequencing through a number of 
alternatives. The error is interpreted as an indication to try the next expression. 
For example, consider the location specification 


(ATTACH (IF (LISTP (## 2)))) 


which says to find the expression with ATTACH as its CAR if the result of exe- 
cuting the expressions in the edit chain yields a list. 

IF may also be used to select between two alternative expressions. It takes 
the form 


*(IF <expression) <commands1) <commands2)) 


When <expression) is evaluated, a non-NIL value selects (commands!) for 
execution, while a NIL value selects <commands2). The IRM notes that this» 
form is equivalent to 


(COMS (CONS 'COMSQ 
(COND 
((CAR (NLSETQ (EVAL X))) 
<commands1) ) 
(T <{commands2) ) ) ) ) 


The IRM notes that the expression 
(IF (READP T) NIL (P)) 
will print the current expression if the read buffer is empty. 


In this form <commands[2]) is optional. But, if evaluating (expression) 
generates an error, then the error will occur. 


19.6.24 Inserting into an Expression 
INSERT inserts one or more S-expressions before, after, or in place of another 
S-expression. It takes the form 


*(INSERT <expri) ... <exprN) (location) <expression)) 


where (location) is one of the keywords BEFORE, AFTER, or FOR. ie 
Suppose that we have a function ENTER that adds a new member to a list if 
it is not already there. At the top level, MEMBER searches the elements of the 
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list to determine if an entry already exists in the list. We would like to add an 
expression that also checks all sublists of the list. We can do this as follows: 


«-(EDITF ENTER) 
edit 
*PP 
(LAMBDA (ENTRY LST) 
(COND 

((MEMBER ENTRY LST) LST) 

((NULL LST) (LIST ENTRY) ) 

(T (APPEND LST (LIST ENTRY) )))) 
*P 
(LAMBDA (ENTRY LST) (COND & & &)) 
*¥3 P 
(COND (& ENTRY) (& &) (T &)) 
*%(INSERT ((EQMEMB ENTRY LST) LST) AFTER 2) 
*P 
(COND (& ENTRY) (& LST) (& &) (T &)) 


where the third element in the above list is the element that we just inserted. 
An alternative command, Insert, evaluates its arguments and inserts the 
results into the current expression. It takes the form 


*(I <command) <expression1) ... (expressionN)) 


I executes the Editor command given by (command). It usually locates the 
position where the expressions will be inserted. (command) may be an atom or a 
list, whence it is also evaluated. The <expression[i]) are evaluated and the 
results inserted into the current expression at the location specific. We could 
have performed the editing indicated above by the following command: 


*(I 3 (QUOTE ((EQMEMB ENTRY LST) LST))) 


If <command) is a list, it will be evaluated. This allows you to specify condi- 
tional locations for insertion, as suggested by the following expression: 


*(I (COND ((NULL FLG) '-1) (T 1)) "APPLES") 


which places the string ‘‘APPLES”’ in a list associated with the index -1 or 1. 
Note that I actually modifies the current expression rather than copying it. 


19.6.25 Joining Conditional Expressions 


The JOIN Conds command merges two neighboring conditional expressions. 
When creating and editing functions, you sometimes add additional checks after 
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the function was written. This may result in the proliferation of superfluous 
COND clauses in your function definition. JOINC allows you to combine two 
COND expressions into one. However, you must be careful to ensure that the 
COND expressions are independent, i.e., they test for different conditions both 
of which may not be true. 


*PP 
. (PROG NIL 
(COND 
((EQUAL Y 10) (PRINT Y))) 
(COND 
((LESSP Y 20) (PRINT (IPLUS Y 12))) 
(T (IMINUS Y 5)))) 
*JOINC 
*PP 
(COND 
((EQUAL Y 10) (PRINT Y)) 
((LESSP Y 20) (PRINT (IPLUS Y 12))) 
(T (IMINUS Y 5))) 


Note that JOINC performs (F COND T) first to locate the first COND of the 
pair to be joined. Thus, you do not have to be properly positioned in order to 
execute JOINC. 

A macro definition for JOINC is (from EDITMACROS) 


(JOINC NIL 
(F COND T) 
UP 
(BI 1 2) 
1 
(BO 2) 
(2) 
(RO 1) 
(BO 1)) 


19.6.26 Locating an S-expression 
The LoCate command allows you to explicitly invoke the location operation. It 
takes the general form 


*(LC . @) 


where @ is a location specification. 
An alternative form, LoCate Local, searches only the current S-expression. 
Consider the following example: 
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*¥PP 
(PROG NIL 
(COND 
((NULL (SETQ L (CDR L))) 
(COND 
(FLAG 
(RETURN L)))) 
((NULL (CDR (MEMBER (CAR L) (CADR L)))))) 
*3 P 
(COND & &) 
*(COND (LCL RETURN) ) P 
(COND 
(FLAG 
(RETURN L))) 


Two alternative forms, 2ND and 3RD, perform two or three LC commands 
in sequence. They may be defined as edit macros as follows: 


(2ND X 
(ORR (LC . X) 
(LC . X))) 
(3RD X 
(ORR (LC . X) 
(LC . X) 
(LC . X))) 


19.6.27 Inserting and Removing Left Parentheses 


The Left In and Left Out commands insert and remove left parentheses from the 
current S-expression, respectively. They take the general form 


*(LI <n)) 
*(LO <n)) 


where <n) is the numerical index of the element before which a left parenthesis 
is to be inserted or removed. 
Consider the following list: 


((Los Angeles 1984) (Moscow 1980) Montreal 1976) 


The last two atoms should actually be components of a list. We can make 
them be a list by executing 


*(LI 3) 
*P 
((Los Angeles 1984) (Moscow 1980) (Montreal 1976) ) 
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Note that LI inserts a left parenthesis before the indicated element and a 
matching right parenthesis at the end of the current S-expression. LI ensures 
balanced parenthesis pairs. 

LO removes the left parenthesis from before the indicated element. It de- 
letes all elements following the (n)th element in the list. 


*(LO 2) 
RE 
((Los Angeles 1984) Moscow 1980) 


19.6.28 Lower-Case Conversion 


LOWER converts all characters of the current expression to lower case. It takes 
the form 


*LOWER 


An alternative form replaces the current expression with the lower-case ex- 
pression. It takes the form 


*(LOWER <expression)) 
It might be defined by an edit macro: 


(LOWER NIL 
(IF (NLISTP (##)) 
UP NIL) 
(I 1 (L-CASE (##))) 


Consider the following example: 


*PP 
(DEFINEQ 
(FACTORIAL (X) 
(* THIS FUNCTION COMPUTES THE FACTORIAL OF x) 
(COND 
((ZEROP X) 1) 
(T 
(ITIMES X (FACTORIAL (SUB1 X))))) 
)) 
*4 
*P 
(* THIS FUNCTION COMPUTES THE FACTORIAL OF X) 
*LOWER 
(* this function computes the factorial of x) 
*OK 
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19.6.29 Iterative Execution 


LP, the LooP command, repeatedly executes its argument list until an error oc- 
curs. It takes the form 


*(LP . <(command)) 
Consider the following example: 


<— (DEFINEQ 
(PRINT.RESPONSE (x) 
(PRINT "The response is'') 
(PRINT x) 
)) 
(PRINT .RESPONSE 


«-(EDITF 'PRINT.RESPONSE) 

*(LP F PRINT (N T)) which places a T at 
the end of every PRINT 
expression 

2 occurrences 

*OK 


<-(PP PRINT.RESPONSE) 
(PRINT .RESPONSE 
(LAMBDA (X) 
(PRINT '"'The response is" T) 
(PRINT X T) 
)) 


Note that when an error occurs, the (command) cannot be applied to the 
current expression. LP terminates and prints a message: (n) OCCURRENCES, 
where <n) is the number of times (command) was successfully executed. The 
edit chain remains in the state established by the last successful execution of 
<command). 

An alternative form, (LPQ . <command)), operates like LP, but it does not 
print the occurrences message. 

It is possible for <command) to force you into an infinite loop. To avoid this 
problem, LP terminates when the number of successful iterations is equal to 
MAXLOOP. MAXLOOP is initially set to 30. Since the edit chain reflects the 
last successful execution, you may continue execution by issuing the REDO 
command (see Section 28.4.1). Setting MAXLOOP to NIL effectively implies an 
infinite number of iterations. 


19.6.30 Macro Definition 


The Macro definition command allows you to create new commands which are 
extensions to the Editor’s repertoire. You may also redefine existing commands 
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via macros whence the macros will take precedence in execution. The format of 
this command is 


*(M <atom) . <command list)) 


The Editor defines <atom) to be an Editor command. Whenever <atom) is 
issued, the commands associated with (atom) are executed. For example, to 
define a backup-and-print command, we could execute the expression 


*(M BP BK UP P) 


where BK, UP, and P are the commands associated with the new command BP. 
If a macro already exists with the name (atom), it will be redefined. Macros 
may use any Editor commands, including other macros, in the definition of new 
Editor commands. 
Many times, you will want to provide arguments to Editor commands to 
make them as general as possible. An alternative format allows you to define a 
list form of a macro as follows: 


*(M (<atom)) (<parameter1) ... <parameterN)) . 
< commands) ) 


The Editor defines (atom) as an Editor command taking N arguments. Ex- 
ecuting an Editor command of the form 


(<atom) <expression1l) ... <(expressionN)) 


causes (expression[i]) to be bound to <parameter[i]) and (commands) to be 
executed. A general form of BP might be defined as 


*(M (BP) (N) (BK N) UP P) 

This format spreads the arguments given with the command across the pa- 
rameters specified by the macro definition. An alternative format allows you to 
define a nospread macro definition. It takes the form 

*(M (<atom)) <parameter) . (commands) ) 

When a macro command of the form 

(<atom) <expressionl) ... ¢(expressionN)) 
is executed, the arguments <expression1) ... <expressionN) are bound to (pa- 


rameter) throughout the definition. The command 2ND may be defined as a 
macro: | 
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*(M (2ND) x 
(ORR ((LC . X) (LC . X)))) 


You should note that the atomic commands are independent of the list form 
commands for both macros and built-in commands. For example, LOWER and 
(LOWER x) are two independent commands that do not conflict with each 
other. However, it is not a good idea to define new commands having both 
atomic and list forms with extremely varying effects. 

A macro definition of M is (from EDITMACROS) 


(M (X . Y) 
(E 
(MARKASCHANGED 
(COND 
((LISTP 'X) 
(CAR 'X)) 
(T 'X)) 
'USERMACROS) 
T) 


(ORIGINAL (M X .. Y))) 


19.6.31 Assigning Values to Arguments 


MAKE assigns a value to a parameter in the current expression. It takes the 
form 


*¥(MAKE <parameter) <value)) 


Consider the following example (assuming the definition for FACTORIAL 
that was given in Section 19.6.28): 


(FACTORIAL Q6) where ''1'' was intended 
instead of ''q"' 

UNBOUND ATOM 

Q6 


—FIX -1 
edit 

¥?= 

X = Q6 
*(MAKE X 16) 
*OK 
32068960256 


MAKE may be defined by an editmacro as follows: 
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(MAKE (VAR . VALS) 
(COMS (MAKECOM VAR VALS) )) 


19.6.32 Making a Function 


MAKEEN converts the current expression to a function. It takes the form 
*(MAKEFN ({function) . <parms)) <arglst) <N1) <N2)) 


where (function) is the function name and <arglst) is a list of its arguments. 
The argument names are substituted for the corresponding argument values in 
{parms). The result of this command becomes the body of the function defini- 
tion for the function. The current expression is replaced by a call to the function 
of the form 


(<function) . <parms)) 


Consider the following example: 


*P 
(COND 
((CAR x) 
(PRINT Y T)) 
(T 
(HELP) ) ) 
*(MAKEFN (AFN (CAR X) Y) (A B))) 
¥P 
(AFN (CAR X) Y) 
¥OK 


«(PP AFN) 
(AFN 
(LAMBDA (A B) 
(COND 
(A (PRINT B T)) 
(T (HELP) )))) 


If <arglst) is omitted, MAKEFN creates an argument list using the ele- 
ments of { parms) if they are literal atoms. Otherwise, it selects argument names 
from the list (X Y Z A B C ...) while avoiding duplicate argument names. 

If <N1) and <N2) are supplied as integer numbers, MAKEFN uses ({N1) 
THRU (N2)) to form the body of the function. If «N2) is omitted, then (¢N1) 
THRU -1) is used. 

MAKEEFEN may be defined by an editmacro as follows: 


(MAKEFN (FORM ARGS N M) 
(IF (QUOTE M) 


alr cries 
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((BI N M) 
(LC. N) 
(BELOW) ) 
((IF (QUOTE N) 
((BI N-1) 
(LC . N) 
(BELOW\) ) 


((LI 1))))) 
(E (MAKEFN (QUOTE FORM) 
(QUOTE ARGS) 


(##) 
T) 
UP 
(1 FORM) 
1) 


19.6.33 Marking and Restoring the Edit Chain 


MARK adds the current edit chain to the front of MARKLST. This allows you 
to save the edit chain for later reference. Consider the following example: 


+ (DEFINEQ 
(NEW. VARIABLE NIL 
(PROG (VARIABLE) 
(SETQ VARIABLE (GENSYM) ) 
(PUTPROP VARIABLE 'VARIABLE T) 
(RETURN VARIABLE) ) 


)) 


<—(EDITF 'NEW. VARIABLE) 
edit 

*3 

*3 

¥3 P 

(GENSYM) 

*MARK 

*0 O P 

(PROG (VARIABLE) (SETQ VARIABLE &) (PUTPROP VARIABLE & ‘e, 
(RETURN VARIABLE) ) 

Xe 

*P 

(GENSYM) 


An alternative form of MARK takes an atom as an argument. It sets the 
atom’s value to be the current edit chain. It takes the form 


*(MARK <atom)) 
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To return to the most recently marked edit chain, you may use the command 
+ (left arrow) command. + sets the edit chain to be (CAR MARKLST). Con- 
tinuing from above: 


*0 0 "move up to SETQ and PROG levels"! 
#4 "move down to PUTPROP"' 
ke "go back to (GENSYM)" 
_ ®P 
(GENSYM) 


If no MARKs have been performed, MARKLST is NIL and + will generate 
an error. ' 

An alternative form, «- + erases the recent mark from MARKLST after it 
has been established as the new edit chain. It is equivalent to performing 


(SETQ MARKLST (CDR MARKLST) ) - 


You may make the current edit chain become the value of an atom using the 
\ command. It takes the form 


*(\ <atom)) 


where (atom)’s value was previously established by a MARK command. For 
complex functions, you may use atoms to store the edit chains at particularly 
crucial points in the code. Returning to one of those points merely requires exe- 
cuting a \ command. If {atom) is NIL, then the current edit chain is set to NIL. 

An alternative form, P, takes you back along the edit chain to the last 
PRINT operation (e.g., one of P, ?, or PP). If the edit chain has not changed 
since the last printing, the edit chain is restored to the one before that. That is, 
two chains are always saved. Consider the following example: 


«-(EDITF 'NEW. VARIABLE) 
editf 

*3 

*2 P 

(VARIABLE) 

*0 

¥4 P 

(PUTPROP VARIABLE 'VARIABLE T) 
*(R 'VARIABLE 'VAR) 
*\P 

(VARIABLE) 


19.6.34 Moving Expressions 


The MOVE command allows you to move S-expressions from one place to an- 
other within an S-expression you are editing. It takes the form 
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*(MOVE @1 TO <command) @2) 


{«command) may be BEFORE, AFTER, or a list command. MOVE oper- 
ates as follows: 


1. Performs (LC @1) to determine the expression to be moved. 


2. Performs (LC @2) to determine the destination to which the expression 
is to be moved. 

3. Performs ({command) @1), e.g., puts the expressions @1 in the S- 
expression relative to @2. 

4. Deletes the expression @1. 


Steps 1, 2, and 3 are performed using the original edit chain. The edit chain 
is unchanged after the execution of a MOVE. UNFIND is set to the current edit 
chain after ({command) @1) is performed. 

Note that @2 cannot specify a location inside @1. An attempt to do so 
causes an error. 

Consider the following example: 


*P 

(hydrogen calcium helium lithium) 
*(MOVE 2 TO AFTER 4) 

*P 

(hydrogen helium lithium calcium) 


19.6.35 Adding to the End of an Expression 


N adds one or more expressions to the end of the current expression. It takes the 
form 


*(N <expression1) ... <expressionN)) 


N modifies the structure of the current expression using RPLACD. 
If the current expression is not a list, N generates an error. 
Consider the following example: 


*P 
(COND 
((ATOM x) x) 
((LISTP x) (CAR x))) 
*(N (T NIL)) 
*P 
(COND 
((ATOM x) x) 
((LISTP x) (CAR x)) 
(T NIL)) 
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19.6.36 Negating the Current Expression 


NEGATE negates the current expression. Its format is 
*¥NEGATE 


It might be implemented by embedding a NOT at the beginning of the cur- 
rent expression via (MDB NOT). However, many expressions, when negated, 
can be further simplified. NEGATE attempts to simplify the expressions that it 
operates upon. 


*P 
(OR 
(NULL x) 
(LISTP x)) 
*NEGATE 
*P 
(AND X (NLISTP x)) 


NEGATE may be defined by an editmacro as follows: 


(NEGATE NIL 
UP 
(I 1 (NEGATE (##1))) 
1) 
19.6.37 Advancing to the Next Expression 


NEX advances to the next expression of the type specified by its argument. Its 
format is 


*NEX 
or 
*(NEX (atom) ) 
A macro definition of NEX is (from EDITMACROS) 


(NEX NIL 
(BELOW +) 
NX) 


and, alternatively, 
(NEX (X) 


(BELOW X) 
NX) 


19.6 An Editor Command Encyclopedia 717 


The atomic form of NEX is useful when you mark an expression in the edit 
chain; you may then use NEX to step through the sublists of the current expres- 
sion. 

Another form is NeXT which advances to the next expression. NX acts like 
UP followed by 2. If the current expression is the last expression in the edit 
chain, NX will generate an error. 

Another alternative form, !NX, makes the current expression be the next 
expression at a higher level in the edit chain unless you are already at the top of 
the edit chain. That is, !NX proceeds through any number of right parentheses 
to match (close) the current expression. 

We can also define a macro, NXP, which moves to the next expression and 
prints it. It has the definition 


(NXP NIL 
(ORR (NX) 
(1NX (E (PRIN ")" T) 
T)) 
((E 
(PROGN 
(SETQQ COM -1) 
(ERROR! ))))) 
P 


19.6.38 The NIL Command 


NIL is usually a no-op, e.g., a no operation command. However, when NIL is 
preceded by F or BF, it indicates that NIL should be sought in the edit chain. 


19.6.39 Finding the Nth Element 


NTH finds the nth element of the current expression. It takes the form 
*(NTH <n)) 


where (n) is not equal to 0. If <n) is greater than zero, it is equivalent to N 
followed by UP. If <n) is less than zero, it is the nth element from the end of the 
current expression. If the current expression does not have (n) elements, an 
error is generated. 

A generalized NTH command takes the form 


*(NTH <command) ) 
This form performs (LCL . <command)) followed by (BELOW \) followed 


by UP. That is, it looks for command) in the edit chain. If the search is unsuc- 
cessful, an error is generated and the edit chain remains unchanged. 
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*P 
(PROG (& &) 
loop 
(COND & &) 
(EDITCOM &) 
(SETQ UNFIND UF) 
(RETURN L)) 
*(NTH UF) 
*¥P 
... (SETQ UNFIND UF) (RETURN L) ) 


19.6.40 Exiting the Editor 


There are three basic commands for exiting from the Editor. OKay exits from 
the Editor and saves the edited expression in the atom with which the Editor was 
invoked. 


<(EDITV COMPLEXFNS) 

edit 

*P 

(CMULT CDIFFERENCE CMINUS CQUOTIENT ...) 


*OK 
COMPLEXFNS 


STOP exits from the Editor with an error. It is mainly used when you want 
to exit the Editor without saving the edited expression. 


<(EDITV COMPLEXFNS) 

edit 

*P 

(CMULT CDIFFERENCE CMINUS CQUOTIENT ...) 


*STOP 


Saving and Exiting the Editor 

SAVE exits from the Editor. The state of the edit chain is saved on the property 
list of the atom that was edited under the property EDIT-SAVE. If the Editor is 
called again on the atom, it checks the property list to see if an edit state exists 
under the property EDIT-SAVE. If so, editing continues from that edit state. 


19.6.41 Using the Original Definition 


When you issue an Editor command, the Editor determines if a macro has been 
substituted for the original command. That is, the value of USERMACROS is 
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searched first for any macro definitions. ORIGINAL instructs the Editor to exe- 
cute all commands which are given as its arguments without considering macro 
definitions. It takes the form 


*(ORIGINAL <(command1) ... <commandN)) 


19.6.42 Executing Any One Command 


ORR begins executing the commands which are its arguments. The first com- 
mand which completes without an error causes ORR to terminate. It takes the 
form 


*(ORR <command1) ... <commandN)) 


Each command is executed in turn. If a command causes an error, ORR 
restores the edit chain to its original value and begins executing the next com- 
mand. If all commands execute with errors (e.g., no command completes suc- 
cessfully), then ORR drops off the end of the command list and generates an 
error. 

NIL is a legal command that always executes successfully. Thus, placing 
NIL at the end of the command list ensures that ORR never generates an error if 
none of the preceding commands does not generate an error. 


(ORR NX !NX NIL) 


attempts to perform an NX, then an !NX, and finally, executes NIL. 


19.6.43 Printing the Current Expression 


The Editor provides a number of commands that print the current expression. 
The basic printing command is Print. It takes the form 


*P 


which means to print the current expression. 
Another form is 


*(P <m) (n)) 


which means print the Mth element of the current expression as though the print 
level were set to (n). If (n) is absent, the Editor assumes a print level of 2, e.g., 


*(P <m)) 


If <m) is 0, it has the same effect as P. If (m) is 0 and <n) is greater than 0, 
it has the same effect as P with a print level of <n). 


720 The INTERLISP Editor 


The command ? is equivalent to (P 0 100). 

Several Editor commands perform prettyprinting. The basic command is 
PrettyPrint, which prettyprints the current expression (see Section 15.7). 

An alternative form, PP*, prettyprints the current expression with com- 
ments. Note that PP merely prints **COMMENT** which is the value of 
**COMMENT**FLG (see Section 16.10.1). 

Another form, PPV, prints the current expression as a variable. That is, it 
provides no special treatment for LAMBDA, SETQ, PROG, or CLISP expres- 
sions. 

Finally, PPT prettyprints the current expression with any CLISP transla- 
tions (see Chapter 23). PPT may be defined as an edit macro as follows: 


(PPT NIL 
(RESETVAR CLISPRETRANFLG T PP)) 


19.6.44 Replacing in an Expression 


The Replace command replaces all instances of one expression in the current 
expression by another. It takes the form 


*(R <x) <y)) 


where (x) and <y) are S-expressions. If there is no instance of (x) in the current 
expression, R generates an error. 

The expression (x) may be an atom or string. If it contains the character 
sequence ${s), e.g., (ESC)<s), then ${s) appearing in <y) will stand for the 
corresponding characters matched in <x). You will be informed of all such re- 
placements by a message of the form, <x) -) <y). Note that this feature may also 
be used to delete characters. (R $1 $) will delete all 1s in the current expression. 
If <x) does not contain ${s), then ${s) appearing in <y) refers to the entire 
expression matched by <x). 

This command is often used to replace characters in an expression. An alter- 
native command, RC, takes the form 


*(RC <x) <y)) 


which is equivalent to (R $(x)$ $<y)$). This form changes all instances of (x) 
to <y). 

Sometimes, you want to change only one instance of a pattern in an expres- 
sion. R1, having the same form as R, changes exactly one instance. RC1, similar 
to RC, changes just one instance of the character. 

REPLACE acts just like R. It takes two forms which are more readable and 
comprehensible: 
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*(REPLACE @ BY <expressionl) ... (expressionN)) 
*(REPLACE @ WITH <expression1l) ... <expressionN) ) 


where @ identifies the expression to be replaced. 


19.6.45 Raising the Case in an Expression 


RAISE raises all the characters in the current expression to upper case. It takes 
one of two forms: 


*RAISE 
or 
*(RAISE <(expression)) 
These may be defined as editmacros as follows: 


(RAISE NIL 
(IF (NLISTP (##)) 
UP NIL) 
(I 1 (U-CASE (##1)))) 
(RAISE (C) 
(I R (L-CASE (QUOTE C)) (U-CASE (QUOTE C)))) 


19.6.46 Editing Atoms or Strings 


REPACK allows you to edit an atom’s print name or a string by recursively call- 
ing the Editor on the UNPACKed list. If the recursion is exited successfully via 
OK, the list of atoms is PACKed into an atom or string to replace the one that 
was edited. The new atom or string is always printed. 

REPACK may be defined as an editmacro as follows: 


(REPACK NIL 
(IF (LISTP (##)) 
(1) 
NIL) 
(ft 3 
((LAMBDA (X Y) 
(SETQ COM (QUOTE REPACK) ) 
(SETQ Y 
(APPLY (QUOTE CONCAT) 
(EDITE (UNPACK X)))) 
(COND 
((NOT (STRINGP X)) 
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(SETQ Y (MKATOM Y)))) 
(PRINT Y T T)))) 
(##) ) 


19.6.47 Right Parenthesis In 


You may insert a right parenthesis into an expression using the Right parenthe- 
sis In command. It takes the form 


*(RI <n) (m)) 


where (n) and <m) are the indices of elements in the current expression. The 
- right parenthesis of the <n) element is inserted (moved) after the <m) element. 


—(SETQ presidents ; 
'((republicans (nixon ford lincoln reagan) ) 
(democrats (kennedy johnson carter 
(whigs) ) )) 
((republicans (nixon ford lincoln reagan) (democrats 
(kennedy jonhnson carter) (whigs))) 


There is a right parenthesis missing after the expression ending in 
CARTER. We can insert it using the following sequence of commands: 


*(EDITV presidents) 

edit 

*¥(RI 2 2) 

¥P 

((republicans &) (democrats &) (whigs)) 


19.6.48 Right Parenthesis Out 


You may remove a right parenthesis from the current expression using the Right 
parenthesis Out command, which takes the form 


*(RO <n)) 


where <n) indicates the Nth element of the current expression. The parenthesis 
is moved to the end of the current expression. All elements following the Nth 
element are moved inside the Nth element. If the Nth element is not a list, an 
error will be generated. Using the example given above, 


<— (EDIT presidents) 
edit 
*P 
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((republicans &) (democrats &) (whigs)) 

*(RO 3) 

*(RO 2) 

*(RO 1) 

*(LO 1) 

*(LO 3) 

*(LO 5) 

*P 

(republicans (nixon ford lincoln reagan) democrats 
(kennedy johnson carter) whigs) 


19.6.49 Setting a Literal Atom’s Value 


723 


You may set a literal atom to the value of the current expression using the Set 


command, which takes the form 


*S <litatom) @ 


where (litatom) is the name of the atom which will be assigned the current ex- 


pression after performing (LC . @). 


<(EDITF CMULT) 

edit 

*P 

(LAMBDA (CX1 CX2) **COMMENT** (PROG & & &)) 
*(S JUNK -1 4) 

*STOP 


— JUNK 
(RETURN CX3) 


19.6.50 Showing Instances 


SHOW displays all of the instances of a given pattern in the current expression. 


It takes the form 
*(SHOW <pattern)) 
Consider the following example: 


<(EDITF initialize. frame) 

edit 

* (SHOW PUTVALUE) 

(PUTVALUE NAME (QUOTE TYPE) NIL) 
(PUTVALUE NAME (QUOTE SUPER) NIL) 
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(PUTVALUE NAME (QUOTE DESCRIPTION) NIL) 
done 


SHOW may be defined as an edit macro as follows: 


(SHOW X 
(F (*ANY* . X) T) 
(LPQ MARK (ORR 1 !0) NIL) 
Pp —_—- — 
(F (*ANY* . X) N)) 
(E (QUOTE done) )) 


19.6.51 Splitting Conditional Expressions 


SPLIT Conds is a command that splits a conditional expression into two condi- 
tional expressions. It takes the form 


*(SPLITC <x)) 


where <x) specifies the last clause in the first conditional (after the split occurs). 
Using the example from JOINC above, consider the following: 


¥PP 

( (COND 
((EQUAL Y 10) (PRINT Y)) 
((LESSP Y 20) (PRINT (IPLUS Y 12))) 
(T (IMINUS Y 5)))) 

*(SPLITC 2) 

*PP 

( (COND 
((EQUAL Y 10) (PRINT Y))) 

(COND 

((LESSP Y 20) (PRINT (IPLUS Y 12))) 
(T (IMINUS Y 5)))) 


SPLITC may be defined as an editmacro as follows: 


(SPLITC (X) 

(F COND T) 

(BI 1 X) 

(IF (AND (EQ (##2 1) T) 
(##2 2 
(NULL (CDDR (##))) 

((BO 2) 
(2)) 
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((-2 COND) (LI 2))) 
UP 
(BO 1)) 


19.6.52 Switching Elements in an Expression 


You may switch elements in the current expression using the SWitch command. 
It takes the form 


*(SW <n) <m)) 


where (n) and <m) indicate the Nth and Mth elements to be switched, respec- 
tively. Consider the following example (after the IRM): 


*PP 

(LIST (CONS (CAR X) (CAR Y)) 
(CONS (CDR X) (CDR Y))) 

*(SW 2 3) 

*P 

(LIST (CONS (CDR X) (CDR Y)) 
(CONS (CAR X) (CAR Y))) 


Note that the relative order of (n) and <(m) is not important; (SW 3 2) 
would have worked equally as well. 
An alternative form, SWAP, switches expressions. It takes the form 


*(SWAP @1 @2) 


where @1 and @2 are location specifications. Thus, using the original expres- 
sion above, 


*PP 

(LIST (CONS (CAR X) (CAR Y)) 
(CONS (CDR X) (CDR Y))) 

*(SWAP CAR CDR) 

¥P 

(LIST (CONS (CDR X) (CAR Y)) 
(CONS (CAR X) (CDR Y))) 


SWAP may be defined as an edit macro as follows: 


(SWAP (LC1 LC2) 
(BIND (MARK #3) 
(ie < 16s) 
(MARK #1) 
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(\ #3) 
(Te. « B62) 
(MARK #2) 
(IF 
(NOT (OR 
(MEMB (CAR #1) #2) 
(MEMB (CAR #2) #1))) 
(UP (\ #1) UP 
(I 1 (CAR #2)) 
(\ #2) 
UP 
(I 1 (CAR #1))) 
(E (QUOTE (nested expressions) )) 
(\ #3))) 


Another alternative form, SWAP Cond clauses, swaps clauses within a con- 
ditional expression. It takes the form 


*(SWAPC <n) <m)) 


where (n) and <(m) indicate the COND clauses to switch. Using the example 
from SPLITC, we have 


*¥PP 

( (COND 
((EQUAL Y 10) (PRINT Y)) 
((LESSP Y 20) (PRINT (IPLUS Y 12))) 
(T (IMINUS Y 5)))) 

*1 

*(SWAPC 2 3) 

*PP 

(COND 
((LESSP Y 20) (PRINT (IPLUS Y 12))) 
((EQUAL Y 10) (PRINT Y)) 
(T (IMINUS Y 5))) 

Note that SWAPC assumes that the current expression is a COND expres- 

sion. Remember that the first element is the COND atom. 


19.6.53 Setting a Tentative Edit Marker 


TEST adds an undo-block at the beginning of the UNDOLST for the Editor. It 
provides a marker that allows you to perform a number of editing changes, and 
then undo them all with a single command, !UNDO. 

UNBLOCK removes an undo-block from the UNDOLST. 

See the description of uNDO for an explanation of their usage. 
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19.6.54 THRU and TO: Location Specification 


The THRU command is used to specify a collection of expressions that can be 
treated as a single element. It is used by EXTRACT, EMBED, DELETE, RE- 
PLACE, and MOVE. It takes the form 


*(@1 THRU @2) 


where @1 and @2 are location specifications. THRU performs (LC . @1), UP, 
(BI 1 @2), 1. This has the effect of grouping the desired expressions into a single 
expression which may be treated by another command. 

The TO command has the same form and effect except that the last expres- 
sion is not included in the grouping. It performs the sequence (LC . @1), UP, 
(BI 1 @2), (RI 1 -2), 1. 

If both @1 and @2 are numbers, and @2 is greater than @1, @ counts 
from the beginning of the current expression. For example, using the following 
list (A B C D E F G), (3 THRU S) means (C THRU E) while (3 TO 5) means 
(C TO E). 

THRU and TO do not do anything useful by themselves. They are very pow- 
erful when combined with other commands as noted above. 


19.6.55 Recursive Editing 


The TTY: command allows you to call the Editor recursively from within the 
Editor. You exit from the lower Editor via OK or STOP. All Editor commands 
are available in the recursed version of the Editor including TTY:. The edit 
chain is preserved across recursive calls to the Editor. 


19.6.56 Undoing an Editor Command 


The Editor maintains an internal list, UNDOLST, which records each change to 
the structure of the current expression by the structure modification commands. 
An Editor command’s effects may be undone using the UNDO command. It 
takes the form 


*UNDO 


This command undoes the effects of the most recent structure modification 
command, e.g., the last entry on UNDOLST. After the effect has been undone, 
it prints the name of the command which was undone. The edit chain is restored 
to the state prior to the undone command. If there are no commands to undo, 
the Editor types NOTHING SAVED. 

An alternative form, !UNDO, undoes all structural changes made during 
the current editing session. As each command is undone, its name is printed. It 
acts like UNDO. 

Note that if a SAVE was performed between calls to the Editor, only 
changes made since the last invocation of the Editor will be undone, i.e., up to 
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the last SAVE. These changes are protected by inserting a marker, called an 
undo-block, into the front of UNDOLST before editing begins in the new ses- 
sion. UNDO (respectively !UNDO) will undo commands up to the marker. 
Note that TEST and UNBLOCK allow you to dynamically insert into and 
remove from UNDOLST your own undo-block markers. 
Undoing changes associated with the I, E, or S commands also undoes the 
side effects associated with the evaluation of the arguments of those commands. 


19.6.57 Moving Up the Edit Chain 


The UP command allows you to move up the edit chain to the next higher ex- 
pression. It takes the form 


*UP <command) 


where (command), an optional argument, indicates that you want to move up 
to the next higher instance of that particular command. 


*PP 
(COND 
((LESSP Y 20) 
(PRINT (IPLUS Y 12))) 
((EQUAL Y 10) 
(PRINT Y)) 
(T 
(IMINUS Y 5))) 
*(F PRINT T) 
*P 
(PRINT (IPLUS Y 12)) 
*UP 
... (PRINT &)) 


19.6.58 Extracting from the Current Expression 
You may extract a subexpression from within the current expression using the 
eXTRact command. It takes the form 


*(XTR . @) 


where @ is a location specification. 
XTR replaces the original current expression with the expression that is ex- 
tracted from it. The new current expression is identified by performing (LCL . 


@). 


*PP 
( (COND 
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((NULL X) 
(PRINT Y)))) 
*(XTR 2 2) 
*P 
((PRINT Y)) 


An alternative form, EXTRACT, takes the form 
*(EXTRACT @1 FROM . @2) 


where @1 and @2 are location specifications. Thus, we could have specified the 
above operation as 


*(EXTRACT PRINT FROM COND) 
*P 
((PRINT Y)) 


19.6.59 Inserting Comments 


You may insert a comment into the current expression using the * command, 
which takes the form 


¥(* . <text)) 


where <text) is the text of the comment. 

The * command ascends the edit chain looking for a safe place to insert the 
comment. These places include after a COND clause, after a PROG clause, af- 
ter the arguments to a LAMBDA expression. It will insert the comment after the 
location if possible; otherwise, before it. 


*PP 
(COND | 
((LESSP Y 20) 
(PRINT (IPLUS Y 12))) 
((EQUAL Y 10) 
(PRINT Y)) 
(T 
(IMINUS Y 5))) 
*3 ~P 
((EQUAL Y 10) (PRINT Y)) 
*(* test Y) 
*PP* 
((EQUAL Y 10) (* test Y) 
(PRINT Y)) 
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19.6.60 Attention-Changing Commands 


Several commands allow you to change the current expression by shifting the 
focus of the Editor. These commands change the edit chain. These commands 
take the form 


*<{n) 
¥-<n) 


where <n) is the index of an element within the current expression. 

If <n) is 0, the edit chain is set to the CDR of the edit chain, thus moving to 
the next higher expression. If there is no higher expression, the Editor generates 
an error. 

An alternative form, !0, performs repeated Os until it reaches a point where 
the current expression is not a tail of the next higher expression. That is, it al- 
ways goes back to the next higher left parenthesis. 

We can define a few simple editmacros that change attention and print the 
result: 


(-1P NIL 
(ORR -1 P) 
((E 
(PROGN 
(SETQQ COM -1) 
(ERROR! ) ) )) 
(2P NIL 
(ORR (2) 
(1) 
((E 
(PROGN 
(SETQQ COM 2) 
(ERROR! ))))) 


20 





Debugging Facilities 


INTERLISP provides a set of integrated facilities for analyzing and modifying 
programs when errors occur. Together, these facilities are known as the Break 
Package. Components of the Break Package are called whenever an error oc- 
curs. They may also be invoked by you through the judicious execution of several 
functions. 

There are three possible modes in which you may initiate a break when your 
program is operating (more or less) normally: 


1. Trace mode where you may view the arguments passed to and results 
returned from a function each time it is computed. 

2. Break mode where you may specify a function is to be interrupted each 
time it is invoked. 

3. Breakin mode where you may insert a breakpoint inside an expression 
that will cause it to be interrupted whenever that expression is executed. 


In the latter two modes, the break commands discussed in Section 20.2 may 
be executed to inspect the state of the computation, change the function defini- 
tion or variable values, and restart the computation. 


20.1 TRACE: TRACING A FUNCTION 


TRACE allows you to identify a function that will be ‘‘traced”’ each time it is 
invoked. It takes the form 


Function: TRACE 

# Arguments: 1 

Argument: 1) an expression, EXPRESSION 

Value: The name of the function to be traced. 


731 


732 Debugging Facilities 


TRACE is an NLAMBDA, nospread function. By tracing, we mean the fol- 
lowing: 


1. When the function is invoked, its parameters are printed with their iden- 
tifying atom names. This action is performed after the values of the argu- 
ments have been determined (subject to the function type — see Section 
8.1). 

. 2. The value of the function is computed. 
3. The result of executing the function is printed. 


TRACE accepts a single argument that is either an atom or a list of expres- 
sions describing the functions to be traced and the parameters to be printed. 
The simplest format for invoking TRACE appears as 


(TRACE <function) ) 


where (function) may be any system- or user-defined function specified as an 
atom. TRACE executes 


(BREAKO <function) T '(TRACE ?= NIL GO)) 


The <function) may not be EVAL. Suppose you tried to trace EVAL. EVAL 
will be called from the READ phase of the top-level loop to evaluate the TRACE 
command. It calls TRACE, which modifies EVAL with the tracing information. 
However, to display a trace requires evaluation, which means that EVAL enters 
an infinite loop while trying to trace itself. 

Suppose we trace the functions REAL, IMAG, ITIMES, PLUS, DIFFER- 
ENCE, and COMPLEX which are called from within the function CMULT. We 
would specify tracing for REAL as follows: 


«(TRACE REAL) 
(REAL) 


«-(SETQ cx1 (COMPLEX 2.0 4.0)) 
((2.0 . 4.0)) 


<-(SETQ cx2 (COMPLEX 3.0 5.0)) 
((3.0 . 5.0)) 


<(CMULT ex1 cx2) 
REAL: 

CX = (( 
REAL = 


2.0 . 4.0)) 
2.0 
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z 
QQ 
iss) 
* 
“ou 
ON Ww 
oo 


. (e.g., more computations traced) 


COMPLEX: 

R = -14 

I = 22 

COMPLEX = ((-14.0 . 22.0)) 


When REAL is traced, the name of its argument is printed and followed by 
its value. ITIMES, because it is a hardwired function, does not have explicit 
variable names, so two are manufactured by the Break Package. 

Alternatively, EXPRESSION may be a list of the form 


(<function) <variable-list) ) 


The CAR of EXPRESSION is the name of the function to be traced, and the 
CDR is a list of variables that are to be printed when the function is traced. 
TRACE executes the expression 


(BREAKO (CAR <expression)) 
T 
(LIST 'TRACE '?= (CDR <expression)) 'GO)) 


Suppose I wanted to see only the value of R for the function COMPLEX. I 
would set up the trace as follows: 


«-(TRACE (COMPLEX R)) 
(COMPLEX) 


<(CMULT cx1 cx2) 

COMPLEX: 

R = -14.0 

COMPLEX = ((-14.0 . 22.0)) 


If you want to see only the value of the function after it has been executed, 
you may use the form 


(< function) ) 
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which causes TRACE to execute the expression 
(BREAKO <function) T '(TRACE ?= (NIL) GO)) 


In general, output generated by tracing functions is sent to your terminal. 
The destination of output is controlled by the system variable BRKFILE whose 
value is initially T. If you want to redirect tracing information to an external file, 
you must set BRKFILE to the name of that file. You are responsible for opening 
the file for output. 


A Definition for TRACE 
We might define TRACE as follows: 


(DEFINEQ 
(trace 
(NLAMBDA x 
(MAPCONC 
(COND 
((ATOM x) 
(* 

Trace a single 
function whose name is 
given. 


) 
(LIST x)) 
(T x)) 
( FUNCTION TRACE-FN) ) 
))) 


(DEFINEQ 
(trace-fn (fn) 
(PROG (brkcoms) 
(COND 
((OR (ATOM fn) 

(EQ (CADR fn) 'IN)) 

(* 
Trace a function modified 
by ADVISE. 


) 
(SETQ brkcoms 
'(TRACE ?= NIL GO) )) 
(T 
(SETQ brkcoms 


(LIST 'TRACE 
19= 
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(OR (CDR fn) 'NIL) 
'GO) ) 
(SETQ fn (CAR fn)))) 
(RETURN 
5 (BREAKO fn T brkcoms) ) ) 


20.2 BREAK COMMANDS 


You interact with the Break Package to determine the status of your function’s 
environment via a set of Break Commands. You may also use the stack access 
and manipulation functions described in Chapter 30. 


20.2.1 Releasing Breaks 


Perhaps the very first thing you need to know is how to get out of a break once 
your function has been broken into. Releasing a break allows a computation to 
proceed. You may use either 


GO Evaluates BRKEXP and prints its 
value. 

OK Evaluates BRKEXP but does not print 
its value. 


BREAK1 (see Section 20.3) evaluates BRKEXP which was set up by the 
function that invoked BREAK 1. The value of BRKEXP is returned as the value 
of the function that was broken. 


«(BREAK MAKESLOT) "declares MAKESLOT breakable" 
(MAKESLOT) 


<-(MAKESLOT 'TEXAS 'CAPITOL 'IS 'SLOT) 
(MAKESLOT broken) 

:GO , 

MAKESLOT = CAPITOL 

CAPITOL 


where MAKESLOT returns the name of the slot as its value. In this case, 
BRKEXP was merely the name of the function to be broken. Thus, executing 
BRKEXP means evaluating the function and printing its value. 

The same example using OK would appear as 


«(BREAK MAKESLOT) "declares MAKESLOT breakable" 
(MAKESLOT ) 


736 Debugging Facilities 


<(MAKESLOT 'TEXAS 'CAPITOL 'IS 'SLOT) 
(MAKESLOT broken) 

:GO 

CAPITOL 


Alternative Versions of GO and OK 
Alternative forms are !GO and !OK. They act as follows: 


1. Unbreak the function 
2. Evaluate the function 
3. Rebreak the function 
4. Execute either GO or OK 


That is, they are equivalent to !EVAL followed by either GO or OK. 


20.2.2 Evaluation in a Break 


You may evaluate the broken function but maintain the break by issuing the 
EVAL command. This command is useful when you have identified a function 
to be broken but are not sure of the value it will produce. 


<(MAKESLOT 'TEXAS 'CAPITOL 'IS 'SLOT) 
(MAKESLOT broken) 

: EVAL 

MAKESLOT evaluated 

: ! VALUE 

CAPITOL 


The Break Package stores the value of the function in the variable !VALUE. 
You may see the value by specifying ! VALUE as shown above. Using EVAL, you 
can see what value the function produces. If it is not the correct value, you may 
invoke the editor to modify the function and, then, re-evaluate it. 


Alternative Form of EVAL 
An alternative form of EVAL is !EVAL, which 


1. Unbreaks the function 
2. Evaluates BRKEXP 
3. Rebreaks the function 


This form is useful for dealing with recursive functions. Evaluating a recur- 
sive function inside a break will cause the function to be broken again. Breaks 
are nested so that the most recent break is attended to first. Thus, EVAL main- 
tains the original break while allowing you to evaluate the function. 
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20.2.3 Returning a Value from a Break 


After a function is broken, you may force the value of the function to be different 
from what would actually be computed by it. The RETURN command has two 
forms: 


RETURN <expression) Evaluates the expression 
and returns its value. 
RETURN (<fn) (arguments) ) Executes the function with 


the given arguments and 
returns its value. 


The RETURN command is useful in a number of ways: 


1. When the function broken is returning the wrong value, you force the 
right value in order to continue testing your program and repair the func- 
tion later. 


When the function returns a correct value, you break it and force an 
erroneous value in order to test the error handling features of your pro- 
gram. 


3. When you are programming using a top-down methodology and the 
function broken is merely a stub. In order to test the logic of higher func- 
tions, you force the function to return a value like that it would have 
computed in order to allow the testing to proceed. 


N 
. 


Consider the folowing example: 


«-(MAKESLOT 'TEXAS NIL NIL NIL) 
(MAKESLOT broken) 

:RETURN 'CAPITOL 

MAKESLOT = CAPITOL 

CAPITOL 


where I failed to provide the name of the slot, but I forced the evaluation to act as 
if I had. 

RETURN is also useful for experimenting with the possible values a func- 
tion might return. You might apply a function to !VALUE after EVALuating a 
broken function. 


20.2.4 Aborting a Break 


You may abort a break by issuing the 1 (up arrow) command which calls ER- 
ROR! (see Section 18.6.2). t effectively erases the stack frame for the broken 
function. This command is useful for unwinding from one or more nested 
breaks. 
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Consider the function CMULT which invokes the functions REAL and 
IMAG. Suppose I specify breakpoints on CMULT and REAL as follows: 


+ (BREAK CMULT) 
(CMULT) 


«(BREAK REAL) 
(REAL) 


-(CMULT ecx1 ecx2) 
(CMULT broken) 


:GO 
ae broken) "here is the second break" 
(CMULT broken) "here we have returned to the 


first breakpoint" 


20.2.5 Unbreaking a Function 


You may unbreak a function by issuing the UB command: 


«(BREAK MAKESLOT) 
(MAKESLOT) 


<-(MAKESLOT 'TEXAS 'CAPITOL 'IS 'SLOT) 
(MAKESLOT broken) 

:UB 

(MAKESLOT) 

:GO 

MAKESLOT = CAPITOL 


UB removes the effect of the BREAK function (see Section 20.3.1) which 
modifies the function to break whenever it is called. 


20.2.6 Displaying Arguments and Bindings 


When a break occurs, you are placed in the Break Package at the current stack 
frame. One of the first things you might want to do is to inspect the bindings of 
the arguments since this is a frequent source of trouble when errors occur. If you 
don’t remember the arguments, you can obtain their names via another com- 
mand. You may also see where a variable is bound in the stack and by which 
functions. These commands are 


?= Prints the argument names and their 
current values. ?= looks for 
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additional arguments on the input 
line. If the line is empty, ?= prints 
all of the arguments of the broken 
function. The remainder of the input 
line may contain the names of 
specific arguments to be printed or 
expressions operating upon the values 
of those arguments. The values are 
printed after the expressions have 
been evaluated. 


ARGS Prints the names of variables bound 
at the current stack frame. 
PB <variable) Prints the bindings of the specified 


variable for each frame in which it 
is found and the name of the frame. 
PB ascends the stack from stack frame 
LASTPOS. 


Consider the following examples: 


«(SETQ ASLOT 'CAPITOL) 
CAPITOL 


«(BREAK MAKESLOT) 
(MAKESLOT) 


*-(MAKESLOT 'TEXAS ASLOT 'IS 'S) 
(MAKESLOT broken) 

= 

NODE = TEXAS 

SLOT = CAPITOL 

INHERITANCE.TYPE = IS 

METHOD = S 


: ARGS 
(NODE SLOT INHERITANCE.TYPE METHOD ) 


:PB NODE 
@MAKESLOT : TEXAS 
@TOP : NOBIND 


The latter line says that NODE is not bound outside of the function call. We 
may also ask where ASLOT is bound (it was provided as an argument to 
MAKESLOT). 
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:PB ASLOT 
@TOP : CAPITOL 


which says ASLOT is a global variable not bound by any function. 
Finally, let us ask for the bindings for LISPXID which is used by LISPX (see 
Section 25.2): 


_ :PB LISPXID 
@LISPX : + 
@EVALQT : +, 
@TOP : NOBIND 


which shows that LISPXID is bound by two functions, LISPX and EVALOQT, to 
the same value. Even so, there are two bindings on the stack. 
?= may take arguments that specify the variables it is to work on. 


(BREAK MAKEDEMON) 
(MAKEDEMON ) 


*-(MAKEDEMON 'TEXAS 
'COUNT-CITIES 


"(LAMBDA NIL 
(COND 
((NULL (GETVALUE NODE 'CITY)) 
0) 
(T 
(LENGTH 
(GETVALUE NODE 'CITY))))) 
"DO 
' S) 
(MAKEDEMON broken) 


: ARGS 

(NODE DEMON FUNCTION INHERITANCE.TYPE METHOD) 
:?= (CAR FUNCTION) 

(CAR FUNCTION) = LAMBDA 


where we extract the CAR of the value of the specified argument. This is equiva- 
lent to saying 


:(CAR FUNCTION) 
LAMBDA 


The difference is that ?= always evaluates its arguments with respect to the 
current stack frame. Thus, using ?= we can evaluate a name at any point in the 
stack if we have previously changed our focus to a different stack frame. 
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?= also accepts numbers as indices to the argument list. Floating point 
numbers are truncated to the nearest integer. 


6?=2 
DEMON = COUNT-CITIES 


£9=2.4 
DEMON = COUNT-CITIES 


Note that ?= prints each variable and its value on a separate line. This 
printing is controlled by BREAKDELIMITER, which initially has the value 
(CR). To modify the appearance of its output, set BREAKDELIMITER to an 
appropriate string. 

Values printed by ?= and PB are printed by SHOWPRINT (see Section 
15.1.3). To prettyprint these values, set SYSPRETTYFLG to T. 


20.2.7 Obtaining a Backtrace 


When you enter a broken function, one of the first things you may want to do is 
to inspect the history of how the function was called. To do so, you obtain a 
backtrace by issuing the BT command. BT prints a backtrace of function names 
only starting at the current position. Typically, this will be the stack frame of the 
broken function (although you may reset it by defining a different value for 
LASTPOS). 


<-(MAKESLOT 'TEXAS 'CAPITOL 'IS 'SLOT) 
(MAKESLOT broken) 
:BT 

MAKESLOT 
\EVALFORM 
\SAFEEVAL 

BREAK1 

\EVALFORM 

EVAL 

LISPX 

ERRORSET 

EVALQT 
\REPEATEDLYEVALQT 
\EVALFORM 
ERRORSET 

\MAKE. PROCESSO 

T 


This example is taken from a Xerox 1100 Scientific Information Processor 
executing the Fugue release of INTERLISP-D. 
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BTV displays the stack frame names and the associated with their func- 
tions: 


*-(MAKESLOT 'TEXAS 'CAPITOL 'IS 'SLOT) 


(MAKESLOT broken) 
:BIV 


MAKESLOT 
*FORM* (MAKESLOT) 
*ARGVAL* NIL 
*TAIL* NIL 
¥FNX MAKESLOT 
\EVALFORM | 
\ INTERNAL BREAK-EXP 
\SAFEEVAL 
BRKEXP (MAKESLOT) 
BRKWHEN NIL 
BRKFN NIL 
BRKCOMS NIL 
BRKTYPE NIL 
ERRORN NIL 
BREAK1 
*FORM* (BREAK1 (MAKESLOT) ) 
\EVALFORM 
\ INTERNAL - 
EVAL 
LISPXID - 
HELPCLOCK 507697 
LISPXHIST ({&) = *) 
HELPFLAG T 
LISPXLISTFLG T 
LISPXLINE NIL 
LISPY NIL 
LISPZ NIL 
LISPXVALUE NIL 
LISPXTEM 93 
LISPX 
ERRORSET 
LISPXID ‘= 
EVALQT 
\REPEATEDLYEVALQT 
*FORM* (\PROC .REPEATEDLYEVALQT) 
*ARGVAL* NIL 
¥TAIL¥ NIL 
¥FN* \PROC .REAPEATEDLYEVALQT 
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where ... indicates that there is additional information necessary to set up the 
virtual machine environment on the Xerox 1100 which does not concern us. 
Variables of the form *{name)* are called blipvalues (discussed in Section 
30.2.3). 

Usually, this information should be enough for any INTERLISP applica- 
tions programmer to examine and modify his or her functions. Indeed, using 
BTV and the stack functions, you may explore the various underlying aspects of 
a particular implementation. You should exercise caution, however, since many 
of the internal functions will change between releases as improvements are made 
to the system. 

Using BTV +, you obtain not only the function variables, but also the local 
variables used by the functions: 


:BTV+ 
*local* MAKESLOT 
*local* a a 
*local* MAKESLOT 
*local* 4 
*local* 0 
*¥local* (LAMBDA 
(NODE SLOT INHERITANCE.TYPE 
METHOD ) 
(BREAK1 & T MAKESLOT NIL) ) 
*local* (NODE SLOT INHERITANCE.TYPE METHOD) 
*local* 4 
*¥local* 8 
*local* 17 
*local* METHOD 
*local* NIL 
*¥local* NIL 
*local* NIL 
MAKESLOT 
*FORM* (MAKESLOT) 
*local* (LAMBDA 
(NODE SLOT INHERITANCE.TYPE 
METHOD) 
(BREAK1 & T MAKESLOT NIL) ) 
*ARGVAL* NIL 
*TAIL* NIL 
*FN* MAKESLOT 
\EVALFORM 
*local* (MAKESLOT) 


... you get the idea. You may see how some of the local variables are used by 
inspecting the code for MAKESLOT when it is compiled. 
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BTV* operates exactly like BTV except that it prints arguments to SUBRs, 


local variables, and temporaries of the interpreter. 


BTV* produces the exact same display as BTV+ under INTERLISP-D. 
Note that INTERLISP-D has no SUBRs. 
You should note that the numbers displayed by BTV+ and BTV* are 


printed as octal numbers. 


BTV, BTV+, and BTV* all take an optional expression that is a functional 
argument that allows you to skip stack frames when displaying the contents of 


the stack. 


20.2.8 Displaying the Entire Stack 


You may display the entire contents of the stack by issuing the BTV! command. 
This command displays all basic frames and their frame extensions (see Section 


30.1) on the stack. 


:BTV! 


Basic 


40160: 
40162: 
40164: 
40166: 
40170: 
40172: 
40174: 


Frame 


40176: 
40200: 
40202: 
40204: 
40206: 
40210: 
40212: 
40214: 
40216: 
40220: 
40222: 


40224: 
40226: 
40230: 
40232: 
40234: 
40236: 


frame at 40174 


ooo0o°0oO 


100400 


xtn at 40176, 
141002 
103524 

40332 
40300 
177777 


0 


51655 
52021 
15071 
pha PE 
51513 
0 
40160 


frame 
40130 
20040 
412 
13427 
0 

5 
51513 
4 

4 
135406 
135272 


0 

10 

15 
15714 
0 

0 


NODE TEXAS 

SLOT CAPITOL 
INHERITANCE. TYPE IS 
METHOD S 


¥local* §MAKESLOT 
[padding] 


name = MAKESLOT 


[V, USE = 2, alink] 
[fn header] 

[next, pc] 

[nametable ] 

[blink, clink] 

¥local* 5 

¥local* §MAKESLOT 
¥local*¥ 4 

¥localx 4 

¥local* (LAMBDA & &) 
*local* (NODE SLOT 
IHERITANCE.TYPE METHOD) 
¥local*¥ 0 

¥local* 8 

*¥local* 13 

¥local* | METHOD 
¥local* NIL 

¥local* NIL 





40240: 
40242: 


40266: 
40270: 
40272: 
40274: 
40276: 
40300: 
40302: 
40304: 
40306: 
40310: 
40312: 
40314: 
40316: 
40320: 
40322: 
40234: 
40236: 
40330: 
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0 0 ¥local* NIL 
177777 0 ¥local* [unbound ] 
through 40264 repeated 
BA tat a go 0 [padding] 

0 51513 [padding] 

0 0 [padding] 

177776 0 

177763 30 
0 0 NIL 
0 0 NIL 


0 51513 MAKESLOT 

10 13400 ([]#0,77400, []#60,174060) 
13621 51604 
51547 15714 


0 0 NIL 

0 0 NIL 

0 0 NOBIND 

2 3 [VMEMPAGEP ]#2, 3 
0 0 NIL 

0 0 NIL 

0 0 NIL 


20.2.9 Setting the Stack Frame 


The break command @ sets the value of the variable LASTPOS. LASTPOS 
indicates the stack frame to be used for evaluation, and thus establishes the con- 
text for several break commands. LASTPOS is the position of a function call on 


the stack. 


@ resets LASTPOS to (STKNTH -1 ‘BREAK1). @ may take several argu- 
ments that appear on the remainder of the input line. These include 


@ 


Leaves LASTPOS as it was and searches from that 
point in the stack. 


Following an atom, it indicates that the next 
atom is a number which specifies that the 
preceding atom should be searched for that many 
times. Thus, CONS is the atom preceding / and 
if it is followed by 3, CONS will be searched 
for three times on the stack. 


Resets LASTPOS to value of the expression which 
follows in the input line. This allows you to 
compute the name of a function dynamically and 
then search for it. 


746 Debugging Facilities 


«n) {«n) is a number that indicates how many stack 
frames up or down the stack you should move in 
setting LASTPOS. 


The action of @ is to process each atom appearing in the remainder of the. 
input line as a direction to search the stack. When the end of the input line is 
reached, LASTPOS will point to a stack frame to be used for evaluating further 
commands. 

@ will fail with the error message “‘(fn) NOT FOUND” if a stack frame 
bearing the name (fn) is not found in the stack. 

Another command, REVERT, uses LASTPOS to specify a function that is 
to be re-entered with the arguments found in the stack. Thus, after an error 
occurs, you may inspect and modify the arguments on the stack, and then re- 
enter the function with the modified arguments. This provides a mechanism for 
restarting a computation where an error is discovered below where it actually 
occurred. You may fix the bug and proceed with the computation. 


20.2.10 Setting Values on the Stack 


Many errors in INTERLISP programs occur because of unbound atoms or unde- 
fined functions. You may dynamically correct these errors by assigning values 
within a breakpoint. 

The = command allows you to assign a value to an unbound atom. It takes 
the form 


:= (expression) 


where (expression) sets the unbound atom appearing at that point in the stack 
frame to the value of (expression). = exits the breakpoint with the assigned 
value and proceeds with the computation. 

The -) command allows you to replace the expression that caused an error 
with the value of its argument. It takes the form 


:-) <expression) 


where expression) is evaluated. This command may be used with either un- 
bound atom or undefined function errors. The value of the expression may be an 
S-expression, perhaps appearing as the argument of QUOTE. 


20.2.11 Breakmacros 


A breakmacro is a definition for a command that is recognized by BREAK1. 
When a command is entered, BREAK1 checks to see if it is a breakmacro. The 
system variable BREAKMACROS is a list of all breakmacro definitions. In the 
Fugue release, it has the following structure: 
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((DBT! 
(DISPBAKTRACE 
(WINDOWPROP (TTYDISPLAYSTREAM) 'BREAKPOS) 
NIL NIL)) 
(DBT 
(DISPBAKTRACE 
(WINDOWPROP (TTYDISPLAYSTREAM) 'BREAKPOS) 
NIL 
' (DUMMYFRAMEP) ) ) 
(BT! 
(BAKTRACE LASTPOS 
NIL 
(BREAKREAD 'LINE) 
0 


T)) 
(BTVPP 
(PROG ((SYSPRETTYFLG T)) 
(BAKTRACE LASTPOS 
NIL 
(CONS 'DUMMYFRAMEP 
(BREAKREAD 'LINE) ) 


1 
T))) 


(BAKTRACE LASTPOS 
NIL 
(BREAKREAD 'LINE) 
0 T)) 


(BT 


(BTV 
(BAKTRACE LASTPOS 
NIL 
(BREAKREAD 'LINE) 
1 
T)) 
(BTV 
(BAKTRACE LASTPOS 
NIL 
(BREAKREAD 'LINE) 
7 


T)) 
(BTV+ 
(BAKTRACE LASTPOS 
NIL 
(BREAKREAD 'LINE) 
5 
T) 
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(BTV! 
(BAKTRACE LASTPOS 
NIL 
(BREAKREAD 'LINE) 
39 
T))) 


_ Note: DBT! and DBT are macros relating to the use of the display facilities 
associated with the Xerox 11xx series computer systems. 


20.2.12 Breakresetforms 


INTERLISP provides many system variables that affect the way the interpreter 
and various functions act. You may modify the action of these functions by reset- 
ting these variables. When a break occurs, if the variables retain their modified 
values, debugging may be difficult to perform. 

BREAKRESETFORMS contains expressions that are used in conjunction 
with RESETFORM or RESETSAVE (see Section 25.7). When a break occurs, 
BREAK 1 evaluates each expression on BREAKRESETFORMS before any in- 
teraction with the terminal. The values of each expression are saved for later 
reinstatement. When you exit the Break Package, the state of the system is re- 
stored by reinstating the values of the expression appearing on BREAKRESET- 
FORMS. If BREAK1 is re-entered before you exit the Break Package, the ex- 
pressions on BREAKRESETFORMS are again evaluated and their values 
saved. 

The initial value of BREAKRESETFORMS is: 


((INTERRUPTABLE T) 
(SETREADMACROFLG) 
(CONTROL) 
(ECHOMODE T)) 


20.3 SETTING BREAKPOINTS 


Functions are not actually broken until they are invoked. You may set a break- 
point for a function using either BREAK or BREAKO. To set a breakpoint, IN- 
TERLISP modifies a function so that it calls BREAK1 upon entry. An example 
of a function having a breakpoint is 


(latlon.to.32bit 
(LAMBDA (a.point) 
(PROG (new.point) 
(BREAK1 
(if (LESSP (fetch xcoord of a.point) 0.0) 
then . 
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(SETQ new.point 
(point.sum a.point 
(point.new 360.0 
90.0))) 
else 
(SETQ new.point 
(point.sum a.point 
(point.new 0.0 


90.0)))) 
T 
(latlon.to.32bit around if) NIL) 
(RETURN 


(point.truncate 
(point.scaleby new.point factor) ))) 
)) 


20.3.1 Function Breakpoints 
BREAK allows you to set a breakpoint for a function. It takes the form 


Function: BREAK 

# Arguments: 1 

Arguments: 1) an expression, EXPRESSION 

Value: A list of the functions which are broken. 


BREAK is an NLAMBDA, nospread function. EXPRESSION may be ei- 
ther an atom or a list. If EXPRESSION is an atom, BREAK performs 


(BREAKO expression T) 
whereas if it is a list, BREAK performs 
(APPLY (FUNCTION BREAKO) expression) 


Note that the structure of the list must correspond to the arguments ex- 
pected by BREAKO. 


A Definition for BREAK 
We might define BREAK as follows: 


(DEFINEQ 
(break 
(NLAMBDA (x) 
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(MAPCONC 


))) 


(COND 
((ATOM x) (LIST x)) 
(T x)) 

(FUNCTION break.1)) 


where BREAK. 1 is defined as 


(DEFINEQ (break.1 (x) 


(COND 


((OR (ATOM x) 


(T 


)) 


(EQUAL (CADR x) 'IN)) 
(breakO x T)) 


(APPLY 'breakO x))) 


The test for the CADR of x picks up the case where we are using the form 


(<fni1)> IN <fn2)). 


20.3.2 Defining a Breakpoint 


BREAKO actually defines a breakpoint for a function. It is invoked by BREAK 
or TRACE. It takes the form 


Function: 
# Arguments: 
Arguments: 


Value: 


BREAKO 


3 


1) a function, FN 
2) a condition for breaking, WHEN 
3) a command list, COMS 


The name of the function. 


BREAKO modifies the definition of FN to call BREAK1 (an example has 
been given above) with BRKEXP equivalent to the original definition of FN. 
WHEN, FN, and COMS are substituted for the values of BRK WHEN, BRKFN, 
and BRKCOMS, respectively. 

The original definition of FN is assigned to an atom created by GENSYM 
(see Section 9.2.1). The name of this atom is stored on FN’s property list under 
the property BROKEN. The definition of the breakpoint is stored on FN’s prop- 
erty list under the property BRKINFO. It has the value (BREAKO <when) 
<coms)). The purpose for storing this information is to allow you to rebreak a 
function at a later time. Finally, FN is added to the list BROKENFNS. 
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«(BREAK point.sum) 
(point.sum) 


«-(GETPROP 'point.sum 'broken) 
(point.sumb0010) 


«-(GETPROP 'point.sum 'brkinfo) 
((BREAKO T NIL)) 


<—(PP point.sumb0010) 
(point.sumb0010 
(LAMBDA (point1 point2) 
(point .new 
(PLUS (fetch xcoord of point1) 
(fetch xcoord of point2)) 
(PLUS (fetch ycoord of pointi1) 
(fetch ycoord of point2))) 
)) 


<-brokenfns 
(point.sum) 


FN may take several different forms. BREAKO processes them as follows: 


1. If FN is not defined, BREAKO displays the message (<function) not a 
function). 


<(BREAKO 'point.divide) 
((point.divide not a function) ) 


2. If FN is a list, it may be a list of functions. BREAKO is invoked for each 
member of the list. The values of WHEN and COMS are used for each 


function. 
If you want to set breakpoints for all the functions in a file, you 


might use the invocation 
(BREAKO (FILEFNSLST <(filename)) <when) <commands)) 


3. FN may have the form (<{fn1) IN <fn2)). This form allows you to set a 
breakpoint on a function, that is called from many functions, within a 
specific function. 

BREAKO changes the name of <fnl) to that of a new function, 
<fn1)-IN-<fn2), wherever it appears in (fn2). It substitutes ¢fn1)-IN- 
<fn2) for ¢fn1) in the expression FN. 

Note: This form works like BREAKIN (see Section 20.3.4), but 
works on compiled functions whereas BREAKIN works only on inter- 
preted functions. 


752 Debugging Facilities 
Consider the following example: 


«(BREAK '((point.sum point.difference point.quotient 
point.times) IN (rectangle.expandby rectangle.center 
rectangle.extent)) (NOT (NULL pointi)) (EVAL (pointi 
point2) ?= OK)) 

(point.sum-in-rectangle.expandby point.sum-in- 
rectangle.center (point.sum not found in 
rectangle.extent) point.difference-in- 
rectangle.expandby ...) 


<brokenfns 
(point.quotient-in-rectangle.center point.difference- 
in-rectangle.extent ...) 


«(PP rectangle.expandby) 
(rectangle.expandby 
(LAMBDA (a.rectangle a.point) 
(rectangle.new 
(point .difference-in-rectangle.expandby 
(fetch origin of a.rectangle) 
a.point) 
(point.sum-in-rectangle.expandby 
(fetch corner of a.rectangle) 
a.point) )) 
)) 


<-(GETPROP 'point.sum-in-rectangle.expandby 'brkinfo) 
((BREAKO (NOT {NULL point1)) (EVAL (PRINT point1) ?= 
OK) ) 


A Definition for BREAKO 
We might define BREAKO as follows: 


(DEFINEQ (breakO (fn when coms) 
(PROG (fn-def brk.condition temp value) 
top 
(SETQ value fn) 
(COND 
((NULL (ATOM fn)) 
(RETURN (break0.subfunction) ) ) 
((NULL (SETQ fn-def (GETD fn))) 
(AND 
(SETQ fn-def (FNCHECK fn T)) 
(SETQ fn fn-def) 
(GO top) ) 
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(PUTPROP fn 'broken (GENSYM) ) 

(* 
If the function is not defined, set 
up the breakpoint anyway. 


(puta fn 
(LIST 'nlambda 
(GENSYM) 
(LIST 'break1 
NIL 
when 
fn 
coms) ) ) 
(SETQ value 
(CONS fn '(not a function))) 
(GO set-brokenfns) ) 
((AND (EXPRP fn-def) 
(LISTP (CADDR fn-def) ) 
(EQUAL (CAADDR fn-def) 'breaki)) 
(* 
If the function is already broken, 
modify the breakpoint. 


) 
(RPLACA 
(SETQ brk.condition (get.when fn-def)) 
when) 
(RPLACD 
(CDR brk.condition) (LIST coms) ) 
(COND 
((SETQ temp 
(ASSOC 'breakO 
(GETPROP fn 'brkinfo)) ) 
(RPLACD temp (LIST when coms) ) 
(RPLACA 'brokenfns 
(CONS fn 
(DREMOVE 
brokenfns) ) ) 
(RETURN (LIST fn))) 
(T 
(SETQ fn-def 
(CONS (CAR fn-def) 
(CONS (CADR fn-def) 
(CDADR 
(CADDR fn- 
def) )))) 
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))) 
(SETQ fn-def (SAVED fn 'broken) fn-def)) 
(putd fn 
(LIST (CAR fn-def) 
(CADR fn-def) 
(LIST 'breaki 
(CONS 'PROGN (CDDR fn-def) ) 
when 
fn 
coms) ) ) 
set-brokenfns 
(COND 
((NULL (MEMBER fn brokenfns) ) 
(RPLACA brokenfns 
(CONS fn brokenfns) )) ) 
(ADDPROP fn 'brkinfo (LIST 'breakO when coms) ) 
(RETURN 
(LIST value) ) ) 
)) 


(DEFINEQ (get-when (expression) 
(CDDR (CADDR expression) ) 


)) 


(DEFINEQ (breakO-subfunction nil 
(COND 
((NEQ (CADR fn) 'IN) 
(MAPCONC fn 
(FUNCTION break0-subfunction.1)))) 





)) 


(DEFINEQ (break0-subfunction.1 (x) 
(breakO x when coms) ) 


)) 


20.3.3 Activating a Breakpoint 
A breakpoint is activated by calling BREAK1 which has been placed in a func- 
tion definition by BREAKO or BREAKIN. It takes the form 

Function: BREAK1 

# Arguments: 6 


Arguments: 1) a break expression, BRKEXP 
2) a condition for breaking, BRKWHEN 
3) an expression to be evaluated, BRKFN 
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4) a list of breakpoint commands, 

BRKCOMS 
5) the type of breakpoint, BRKTYPE 
6) an error indication, ERRORN 


Value: Determined by the Break Package commands. 


BREAK 1 is an NLAMBDA function. 

BRKWHEN determines whether or not a break is to occur. Usually, 
BRKWHEN is an expression that tests some condition of the variables or argu- 
ments used by the function to be broken. If BRKWHEN evaluates to NIL, 
BRKEXP is evaluated and its value is returned as the value of BREAK1. 


«(BREAKIN sum.list (AFTER GO)) 
searching... 
SUM.LIST 


«-(EDITF sum.list) 
Note: you are editing a broken function 
EDIT 
*PP 
(LAMBDA (x) 
(PROG (y sum) 
(SETQ y (COPY x)) 
(SETQ sum 0) 
loop 
(COND 
((NULL y) 
(RETURN sum) )) 
(SETQ sum (PLUS sum (CAR y))) 
(SETQ y (CDR y)) 
(GO loop) ) 
(BREAK1 NIL T (SUM.LIST after GO) NIL)) 
*OK 
(SUM.LIST) 


where BRK WHEN has the value (AFTER GO). 

When a break occurs, ERRORN is inspected. If it is a list whose CAR is a 
number, ERRORMESS (see Section 18.6.1) is called to print an identifying 
message. If its CAR is not a number, ERRORMESS1 is called to print the mes- 
sage. Otherwise, no preliminary message is printed. Normally, you do not define 
ERRORN. After this, the message ((brkfn) broken) is printed. 

The Break Package executes the commands that it finds in BRKCOMS, if 
any. If none of these commands exits the break, the Break Package prints its 
prompt (e.g., :) and accepts commands from the terminal, and interprets them. 
You may only leave a breakpoint using the commands GO, !GO, OK, !OK, 
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RETURN, and f (up arrow). EVAL evaluates BRKEXP and stores its value in 
the variable !VALUE, whence it may be inspected. You may define other com- 
mands via BREAKMACROS. 

BRKTYPE specifies the type of break. It takes the values 


NIL for user-specified breakpoints 
INTERRUPT for CTRL-H breakpoints 
- ERRORX for error breakpoints 


20.3.4 Breaking into a Function 


BREAK allows you to set a breakpoint for an entire function. Sometimes, you 
may want to break within a function, particularly one which is lengthy or com- 
plex. To do so, you can use BREAKIN which inserts a call to BREAK1 before, 
after, or around a choice expression within a function. 

A breakpoint is inserted by a sequence of editor commands. Alternatively, 
you may enter the Editor from BREAKIN, search for the proper location your- 
self, and exit, whence the breakpoint is inserted before, after, or around the 
current expression. 

BREAKIN takes the form 


Function: BREAKIN 
# Arguments: 4 


Arguments: 1) a function name, FN 
2) a location, WHERE 
3) a condition for breaking, WHEN 
4) a command list, COMS 


Value: The name of the function. 


BREAKIN is an NLAMBDA function. 

FN must be a function which is modifiable (i.e., an interpreted function). 
BREAKIN returns ({name) not a function) if the function is undefined or 
(<name) unbreakable) if it is compiled. 

When BREAKIN is called on an interpreted function, it displays the mes- 
sage “‘searching ...” while it calls the Editor to look for the current expression 
matching the WHERE specification. WHERE specifies the location at which 
the call to BREAK1 will be inserted as modified by WHEN. 


(DEFINE 
(convert.latlon.to.32bit (latlon) 
(PROG (new.point) 
(if 
((LESSP latlon:xcoord 0.0) 
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then (SETQ new.point 
(point.sum latlon 
(point.new 360.0 
90.0)))) 


else (SETQ new.point 
(point.sum latlon 
(point.new 0.0 
90.0))))) 
(RETURN 
(point.truncate 
(point.scaleby new.point factor) ))) 


)) 


Let us break this function around the if...then...else expression: 


«(BREAKIN convert.latlon.to.32bit (AROUND if) T) 
searching... 
CONVERT. LATLON.TO.32BIT 


«-(EDITF convert.latlon.to.32bit) 
Note: you are editing a broken function 
EDIT 
*¥PP 
(LAMBDA (latlon) 
(PROG (new.point) 
(BREAK1 
(if 
((LESSP latlon:xcoord 0.0) 
then (SETQ new.point 
(point.sum latlon 
(point.new 360.0 90.0)))) 


else (SETQ new.point 
(point.sum latlon 
(point.new 0.0 90.0))))) 
T (around if) NIL) 
(RETURN 
(point. truncate 
(point.scaleby new.point factor) ))) 


)) 
*OK 
(CONVERT. LATLON. TO. 32BIT) 


When a function is broken into, BREAKIN adds the property BROKEN-IN 
to the function names’ property list with the value T. It also adds the property 
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BRKINFO to the property list with the value (where) <when) <coms)). FN is 
added to the list BROKENFNS. 


«-(GETPROP 'convert.latlon.to.32bit 'BROKEN-IN) 
T 


“(GETPROP 'convert.latlon.to.32bit "BRKINFO) 
(((AROUND if) T NIL)) 


You may insert multiple breakpoints in a function by setting WHERE to a 
list of expressions each of which specifies a location at which the function is to be 
broken. 


“(BREAKIN convert.latlon.to.32bit 
((BEFORE PROG) (AFTER point.scaleby) 
(AROUND if) (AFTER RETURN) ) 
(NOT (NULL lation) )) 
searching... 
a i inserted AFTER (RETURN (POINT.TRUNCATE 
& 
searching... 
searching... 
CONVERT. LATLON.TO.32BIT 


<(GETPROP 'convert.latlon.to.32bit 'BRKINFO) 

(((BEFORE PROG) (NOT (NULL latlon)) NIL) ((AFTER 
point.scaleby) (NOT (NULL latlon)) NIL) ((AROUND if) (NOT 
(NULL latlon)) NIL) ((AFTER RETURN) (NOT (NULL latlon)) 
NIL) ) 


Note that WHEN is used for each breakpoint. 

If you do not know where you want to insert a breakpoint, you may specify 
the form (BEFORE TTY:) or (AFTER TTY:) as the value of WHERE. 
BREAKIN invokes the Editor. You may then search for the proper location at 
which to insert the breakpoint. When you exit from the Editor via OK, 
BREAKIN inserts the call to BREAK1 before, after, or around the current ex- 
pression. To exit without inserting a breakpoint, type the command STOP to 
TTY::. It acts like an unsuccessful edit command in the original form. The Edi- 
tor aborts. BREAKIN returns (not found) after the “‘searching...’’ message. 

BREAKIN prevents you from inserting breakpoints inside an expression 
that would never be activated. The variable NOBREAKS is a list of atoms. Ini- 
tially, its value is(GO QUOTE *). If you attempt to insert a breakpoint inside an 
expression beginning with one of these atoms, BREAKIN will not permit it. You 
may add to NOBREAKS additional atoms that would begin expressions you do 
not wish to be broken into. However, you should exercise caution in selecting the 
atoms to be added. 
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Consider the following example: 


«(PP SUM.LIST) 
(LAMBDA (x) 
(PROG (y sum) 
(SETQ y (COPY x)) 
(SETQ sum 0) 
loop 
(COND 
((NULL y) (RETURN sum) )) 
(SETQ sum (PLUS sum (CAR y))) 
(SETQ y (CDR y)) 
(GO loop) )) 


«(BREAKIN sum.list (AFTER GO) ) 
searching... 
SUM. LIST 


<(EDITF sum.list) 
Note: you are editing a broken function 
EDIT 
*PP 
(LAMBDA (x) 
(PROG (y sum) 
(SETQ y (COPY x)) 
(SETQ sum 0) 
loop 
(COND 
((NULL y) 
(RETURN sum) )) 
(SETQ sum (PLUS sum (CAR y))) 
(SETQ y (CDR y)) 
(GO loop) ) 
(BREAK1 NIL T (SUM.LIST after GO) NIL)) 
*OK 
(SUM.LIST) 


For BEFORE or AFTER commands, BREAKIN ensures that the break- 
point is inserted in a “‘safe’’ place: 


«(BREAKIN sum.list (AFTER TTY:)) 
EDIT 

*3 

*7 

*2 

*OK 
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break inserted AFTER (SETQ SUM (PLUS SUM &)) 
SUM. LIST 


The three numbers above are Editor commands to descend into the struc- 
ture of SUM.LIST. In fact, they make the current expression be SUM in the 
(SETQ SUM ...) expression. BREAKIN does not allow you to insert a break- 
point in the middle of an expression, so it places it ‘‘safely’” after the expression. 


20.3.5 BREAKCHECK: When to Break 


When an error occurs, INTERLISP must decide what action to take: either un- 
wind the stack or go into a break. If a computation has proceeded only a little 
way, such as hitting a misspelled function name at type-in, INTERLISP usually 
wants to unwind the stack, print an error message, and have you try again. In 
the midst of a complex computation, the best tactic is to go into a break. The 
decision on entering a break depends on the depth (e.g., number of function 
calls) of the computation and the amount of time invested in it. BREAKCHECK 
is called to determine if a break should occur. It takes the form 


Function: BREAKCHECK 

# Arguments: 2 

Arguments: 1) an error position, ERRORPOS 
2) an error number, ERXN 

Value: T, if a break should occur; otherwise, 
NIL. 


BREAKCHECK is called when an error is encountered. It must decide 
whether or not to induce a break. 
ERRORPOS is the stack position where the error occurred, i.e., it is a stack 


pointer to the frame representing the function in which the error occurred. . 


ERXN is an error number. 

BREAKCHECK returns T to indicate that a break should occur if the depth 
of the stack is greater than HELPDEPTH. HELPDEPTH is initially set to 7, but 
you may reset it. 

If the stack length (in frames) is less than HELPDEPTH, BREAKCHECK 
calculates the time spent in the computation. If the time is greater than HELP- 
TIME (in milliseconds), BREAKCHECK will return T to indicate that a break 
should occur. HELPTIME is initially set to 1000 (milliseconds). 

BREAKCHECK searches backwards in the stack from ERRORPOS look- 
ing for an ERRORSET frame. If the stack is to be unwound, INTERLISP will 
do so back to the ERRORSET ftame. At the same time, it counts the number of 
invocations of EVAL. When the number of calls to EVAL exceeds HELP- 
DEPTH, BREAKCHECK returns T. Otherwise, it searches until an ERROR- 
SET frame is found or the top of the stack is reached. It then counts the number 
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of function calls between the ERRORSET frame (or the top of the stack). The 
number of functions calls plus the number of calls to EVAL is used as the com- 
putation depth. If it exceeds HELPDEPTH, BREAKCHECK returns T. 

The computation time is determined by subtracting the value of HELP- 
CLOCK from the value of a call to CLOCK, which reads the system clock. 
HELPCLOCK is the last recorded value of a call to CLOCK for each call to 
LISPX. If this exceeds HELPTIME, BREAKCHECK returns T. You may dis- 
able the time citerion for breaking by setting HELPTIME to NIL or a very large 
number. 

You may disable all error breaks by resetting the variable HELPFLG to NIL 
using SETTOPVAL (e.g., you must set the top-level value). HELPFLG is re- 
bound during calls to LISPX (e.g., in a stack frame so assigning a value via 
SETQ just affects the most recent binding). You may force a break to occur on 
every error by rebinding the top-level value of HELPFLG to BREAK!. 


20.4 UNBREAKING FUNCTIONS 


You may unbreak functions in two ways: either issuing the UB command from 
within the break or executing a function. Functions to unbreak functions are 
described in this section. 


20.4.1 Unbreaking a Function: 1 


UNBREAK removes a breakpoint from one or more functions. Its takes the 
form 


Function: UNBREAK 

# Arguments: 1 

Argument: 1) an expression, EXPRESSION 

Value: A list of functions that are unbroken. 


UNBREAK is an NLAMBDA, nospread function. 

EXPRESSION may be atomic or a list of atoms that are function names. 
Each function is unbroken via a call to UNBREAKO. Its value is the list of values 
returned by UNBREAKO. 

UNBREAK will unbreak functions that have been broken by BREAK, 
BREAKO, TRACE, or BREAKIN. 

If EXPRESSION is NIL, UNBREAK will unbreak all functions on BRO- 
KENFNS. BRKINFOLST is first set to NIL: 


+ (UNBREAK) 
(point.sum point.difference point.quotient) 


If EXPRESSION has the value T, UNBREAK unbreaks the first function 
on BROKENENS. Since BREAK, BREAKO, BREAKIN, or TRACE always 
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add a newly broken function to the front of the list, the effect is to unbreak the 
most recently broken function. 


«(BREAK point.sum) 
(point.sum) 


«(BREAK point.difference) 
(point.difference) 


<-BROKENFNS 
(point.difference point.sum) 


<—(UNBREAK T) 
(point.difference) 


A Definition for UNBREAK 
We might define UNBREAK as follows: 


(DEFINEQ unbreak 
(NLAMBDA x 
(COND 
((EQUAL (CAR x) T) 
(SETQ x (LIST (CAAR brokenfns) ) )) 
((NULL x) 
(SETQ x (REVERSE brokenfns) ) 
(RPLACA 'brokenfns NIL) 
(RPLACA 'brkinfolst NIL))) 
(MAPCONC x (FUNCTION unbreak0) ) 


))) 


20.4.2 Unbreaking a Function: 2 


The workhorse for unbreaking functions is UNBREAKO. It restores a function 
to its original state. UNBREAKO takes the form 


Function: UNBREAKO 

# Arguments: 1 

Arguments: 1) a function name, FN 
Value: The value of FN. 


FN is treated as follows: 


1. If FN is atomic, and was not broken, UNBREAKO displays the message 
(<fn) not broken) and does nothing. 
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(UNBREAKO 'point.sum) 
(point.sum not broken) 


2. If FN is atomic and was modified by BREAKIN, UNBREAKIN is called 
to remove these modifications. 

3. If FN is atomic, it is restored to its original state. 

4. If FN has the value <fnl)-IN-(fn2), UNBREAKO restores <fn2) to its 
original state. All dummy functions created as a result of the breakpoint 
are eliminated. 


5. If FN is a list of the form (<fn1) IN ¢fn2)), UNBREAKO operates on the 
functions <fn1)-IN-<fn2) as in case (4) above. 


The value of UNBREAKO is the name of the function that is restored. 


20.4.3 Unbreaking a Broken-into Function 


UNBREAKIN allows you to remove a breakpoint that was inserted into a func- 
tion by BREAKIN. It performs the proper editing actions to remove the break- 
point and restore the function to its original state. It is automatically called by 
UNBREAK if a function has the property BROKEN-IN. It takes the form 


Function: UNBREAKIN 

# Arguments: 1 

Argument: 1) a function name, FN 
Value: The value of FN. 


20.5 BREAK PACKAGE UTILITIES 


Several functions are useful for writing breakmacros and modifying functions. 
They are gathered here as utility functions. 


20.5.1 Reading Break Package Commands 


As discussed in Section 20.2.11, you may create your own breakpoint commands 
as macros that are executed by functions that you specify. When you give a 
breakmacro as an element of BRKCOMS, you must be able to read any argu- 
ments that are associated with the command. BREAKREAD allows you to read 
elements from BRKCOMS. It takes the form 


Function: BREAKREAD 
# Arguments: 1 
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Arguments: 1) A type specification, TYPE 
Value: The next elements in BRKCOMS or the input. 


If BRKCOMS is non-NIL for any Break Package function, BREAKREAD 
returns the next command in the list. And it sets the BRKCOMS list to its CDR. 

If TYPE is LINE and the break command was typed in at the terminal, 
BREAKREAD returns the rest of the input buffer (up to a <CR)). 


A Definition for BREAKREAD 
We might define BREAKREAD as follows: 


(DEFINEQ 
(breakread (flag) 
(COND 
(brkcoms 
(PROG1 
(CAR brkcoms) 
(SETQ brkcoms (CDR brkcoms) ))) 
((EQUAL flag 'LINE) 
(READLINE) ) 
(T 
(CAR (READLINE)) ) 
)) 


Note that we use READLINE rather than READ when a macro expects 
some input, because READLINE will wait for you to type something in while 
READ will return NIL. 


20.5.2 Changing Names in Functions 
CHANGENAME changes all occurrences of a name FROM to a name TO ina 
function FN. It is primarily used by break functions to handle the form (<fn1) 
IN <fn2)). It takes the form 

Function: CHANGENAME 

# Arguments: 3 


Arguments: 1) a function, FN 
2) a from name, FROM 
3) a to name, TO 


Value: FN if FROM is found; otherwise, NIL. 


CHANGENAME will change any names within FN, not just function 
names. It does not perform any modifications on property lists. 
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20.5.3 Restoring a Virgin Definition 


VIRGINEN knows how to restore the original state of a function regardless of 
the number of times that it has been advised, broken, broken-in, or traced. It 
takes the form 


Function: ’ VIRGINFN 
# Arguments: 2 


Arguments: 1) a function name, FN 
2) a flag, FLAG 


Value: The original definition of the function. 


VIRGINEN is used by a number of system functions to restore a function to 
its original state including PRETTYPRINT, DEFINE, and the compiler. FLAG 
determines whether the function is modified or a copy is made. PRETTYPRINT 
calls VIRGINFN with FLAG equal to NIL so that a copy is made, i.e., if you 
want to prettyprint a function without any of the encumbering detail that is 
added by advising, breaking, or tracing the function. If FLAG is T, as specified 
by the compiler and DEFINE, VIRGINEN physically restores the function to its 
original state. It also tells you what changes it has made, e.g., one of (FN) UN- 
BROKEN, <FN) UNADVISED, or (FN) NAMES RESTORED. 


20.5.4 Printing a Backtrace of the Stack 


BAKTRACE implements the BT, BTV, BTV+, BTV*, and BTV! commands 
of the Break Package. It takes the form 


Function: BAKTRACE 
# Arguments: 4 


Arguments: 1) an initial stack position, IPOS 
2) an ending stack position, EPOS 
3) a skipping function, SKIPFN 
4) options, FLAGS 


Value: A display of the stack from IPOS to EPOS 
subject to the actions of SKIPFN and the 
values of FLAGS. 


IPOS and EPOS are stack frame specifications as described in Section 30.3. 

SKIPEN is a function that determines whether or not to print the informa- 
tion for a stack frame. If SKIPFN is non-NIL, it is applied to the value of 
(STKNAME (POS)). If the value is T, the current position is skipped (i.e., not 
printed). 
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FLAGS specifies the display options for the backtrace. It takes the values 
for the corresponding commands: 


Value Command 
0 BT 
1 BTV 
5 BTV+ 
yi BTIV* 
47Q BTV! 


When BAKTRACE prints information about a stack frame, it will abbrevi- 
ate information about various sequences of function calls by a single entry. The 
function calls to be abbreviated are given by BAKTRACELST. Each entry on 
BAKTRACELST is a list of the form 


(<framename) (key) . <pattern)) 
or 
(<framename) (<{key1) . <pattern1)) 
(<keyN) . <patternN)) ) 
where a (pattern) is a list of elements that have either atoms, which match a 


single frame, or lists, which are interpreted as a list of alternative patterns. 
For the Fugue Release of INTERLISP-D, BAKTRACELST has the follow- 


ing format: 


( (APPLY 
( **BREAK** 
LISPX ERRORSET BREAK1A BREAK1) 
(**TOP#* 
LISPX ERRORSET EVALQT T) 
( **EDITOR** 
LISPX ERRORSET ERRORSET ERRORSET EDITL1 
EDITLO ERRORSET 
((ERRORSET ERRORSET ERRORSET EDITL1 EDITLO 
ERRORSET) -) 
EDITL ERRORSET ERRORSET EDITE ((EDITF) 
(EDITV) 
(EDITP) 
-)) 
( **USEREXEC** 


LISPX ERRORSET ERRORSET USEREXEC) ) 
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(EVAL 
(**BREAK** 
LISPX ERRORSET BREAK1A BREAK1) 
(**TOPXX 
LISPX ERRORSET EVALQT T) 
(**EDITOR¥* 
LISPX ERRORSET ERRORSET ERRORSET EDITL1 
EDITLO ERRORSET 
((ERRORSET ERRORSET ERRORSET EDITL1 EDITLO 
ERRORSET) -) 
EDITL ERRORSET ERRORSET EDITE ((EDITF) 
(EDITV) 
(EDITP) 
-)) 
(**USEREXEC** 
ERRORSET LISPX ERRORSET ERRORSET USEREXEC)) 
(PROGN 
¥XBREAK** 
EVAL 
((ERRORSET BREAK1A ERRORSET BREAK1) 
(BREAK1) ) 
(BLKAPPLY 
¥¥BREAK#* 
PROGN EVAL ERRORSET BREAK1A ERRORSET BREAK1) 
(*PROG*LAM 


(NIL EVALA *ENV*) 
(NIL CLISPBREAK1) ) ) 


BAKTRACE scans the stack frame by frame. At each frame, it compares 
the current frame name with the frame names that appear on BAKTRACELST 
using ASSOC. If the current frame name appears, it attempts to match a contig- 
uous set of stack frames with each of the pattern(s). If a match is unsuccessful, 
BAKTRACE prints the corresponding key, and continues from the point where 
the match was successful. If the frame does not appear or the match fails, 
BAKTRACE simply prints the frame name, unless SKIPFN applied to the 
frame name is non-NIL. It then proceeds to the next higher frame. 

In constructing patterns, you may use the following features: 


1. The atom & can be used to match any frame, i.e., it is equivalent to 
“don’t care.”’ 

2. The atom—(e.g., a dash) can be used to match nothing, i.e., it can be 
used for optional matches. 
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- You do not have to provide matches for dummy frames, i.e, frames for 


which DUMMYFRAMEP (see Section 30.5.1), is true. When matching, 


the matcher automatically skips over these frames when they do not 
match. 


. If the match succeeds and the key is NIL, nothing is printed (see the last 


expression for *PROG*LAM above). 
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Advising 


Advising is a means of altering the interface to a function. Alteration may occur 
before or after the function is executed. As a user, you do not need to know how a 
function works (usually) to modify its interface with its environment. BREAK, 
TRACE, and BREAKDOWN all use advising to effect the operation of func- 
tions. 

You may advise functions so that they are affected every time they are 
called, or when they are called within or by another function. The IRM notes 
that you may advise TIME as follows: 


“(ADVISE 'TIME 

"BEFORE 

'(SETQQ U FOO) 

'(PRIN1 PRINT SPACES) ) 
TIME 


This advice alters TIME so that it prints its results to the file FOO rather 
than to the terminal. 


21.1 ADVISE: MODIFYING A FUNCTION’S INTERFACE 


You may advise a function or functions by executing ADVISE, which takes the 
following format 


Function: ADVISE 
# Arguments: 4 


Arguments: 1) a specification, FNS 
2) the time of alteration, WHEN 
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3) the location of alteration, WHERE 
4) the advice, WHAT 


Value: The name of the function(s) advised. 


FNS is a specification that describes the function(s) to be altered. It may 
take one of several forms: 


“1. If FNS is an atom, it is a single function to be advised. 
2. If FNS takes the form 


(fns.1 IN fns.2) 


then FNS.1 is altered throughout FNS.2. If either or both of FNS.1 and 
FNS.2 are lists of functions, the names are totally distributed across both 
lists. 


If FNS is being advised for the first time, then ADVISE modifies the 
functions as follows: 


~ 


a. It creates a new symbol using GENSYM. 

b. The new symbol is given the original definition of 
FNS. 

c. The name of the new symbol is placed on the property 
list of FNS under the property ADVISED. 

d. An appropriate S-expression version of FNS is 
created for FNS. 

e. FNS is added to the list ADVISEDFNS. 

f. The list (WHEN WHERE WHAT) is stored under the 
property ADVICE on the property list of FNS. 


4. If FNS is a list of functions, each function is advised in turn with a i of 
the other three arguments. 


A function may be advised when it is broken. If so, it is unbroken before it is 
advised. If a function has been advised before (because the ADVISED property 
exists), it is merely moved to the head of ADVISEDFNS. 

If FNS is not defined, ADVISE displays an error message “NOT A FUNC- 
TION” and breaks. 

WHEN may take the values BEFORE, AFTER, or AROUND. If it has the 
value BEFORE or AFTER, the advice is inserted into the function’s definition 
before or after the location specified by WHERE. If WHEN has the value 
AROUND, then the advice has a * within its form and the body of the function is 
inserted in place of the *. 


errr 
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WHERE specifies the location of the advice in the function definition. You 
may place advice around the entire body of a function or specific functions 
within the function. We may advise READ to print its value each time it is exe- 
cuted using the following expression: 


«(ADVISE 'READ 'AFTER '(PRIN1 ! VALUE) ) 
READ 


WHERE may take the values LAST, BOTTOM, END, or NIL. If so, the 
advice is added following all other advice, if any. If WHERE has the value TOP 
OR FIRST, the advice will be inserted as the first piece of advice. Thus, a func- 
tion may be subject to multiple pieces of advice both before and after its execu- 
tion. 

What does an advised function look like? If we execute the expression 


(ADVISE 'point.sum 
'T 
'(BEFORE PLUS) 
'(PRIN1 "EXECUTING PLUS") 


we obtain the following definition for POINT.SUM: 


<(EDITF 'point.sum) 
Note: you are editing an advised function 
EDIT 
*PP 
(LAMBDA (point1 point2) 
(ADV-PROG (!value) 
(ADV-SETQ !value 
(ADV-PROG NIL 
(ADV-RETURN 
(PROGN 
(point.new 
(PLUS point1:xcoord 
point2:xcoord) 
(PLUS point1:ycoord 
point2:ycoord) ))))) 
(ADV-RETURN !value) )) 


A Definition for ADVISE 
We might define ADVISE as follows: 


(DEFINEQ 
(advise (fns when where what) 
(PROG (fns.1 fns.2 fns.def) 
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(COND 
((ATOM fns) 
(SETQ fns (FNCHECK fns)) 
((EQUAL (CADR fns) 'IN) 
(SETQ fns.2 (CADDR fns)) 
(RETURN 
(COND 
((ATOM (SETQ fns.1 (CAR fns))) 
(COND 
((ATOM fns.2) 
(advise1 fns.1 fns.2)) 
T 
(MAPCAR fns.2 (FUNCTION 
advise2) ))) 
((ATOM fns.2) 
(MAPCAR fns.1 (FUNCTION 


advise3) ) ) 
(T 
(MAPCONC fns.1 (FUNCTION 
advise4)))))) 
(T 
(RETURN 
(MAPCAR fns (FUNCTION 
advise5))))) 
(COND 


((OR what (NULL when)) NIL) 
((NULL where) 
(* 
Advise[<{function) <advice)] 
is the same as 
advise[<{function) BEFORE NIL 
{advise) ] 
) 
(SETQ what when) 
(SETQ when 'BEFORE) ) 
(T 
(SETQ what where) 
(SETQ where NIL))) 
(RESTORE fns "BROKEN ) 
(SETQ fns.def (GETD fns)) 
(COND 
( (NULL fns.def) 
(PRIN1 fns) \ 
(SPACES 1) 
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(PRIN1 "not defined.'') 
(TERPRI) ) 
((OR (NULL (EXPRP fns.def) ) 
(NULL (GETP fns "ADVISED) ) ) 
(SETQ fns.2 (SAVED fns 'ADVISED 
fns.def) ) 
(PUTD fns 
(LIST (CAR fns.2) 
(CADR fns.2) 
(SETQ fns.2 
(SUBPAIR 'DEF 
(LIST 
(COND 
((CDR 
(SETQ fns.2 
(CDDR 
fns.2))) 
(CONS 'PROGN 
fns.2)) 
(T 
(CAR 
fns.2)))) 
(COPY ADVISE- 
FORM) ) )) )) 
(T 


(SETQ fns.2 (CADDR fns.def)))) 

(* 
Moving a function that is already 
advised to the front of the list of 
advised functions. 


) 
(SETATOMVAL 'ADVISEFNS 
(CONS fns 
(/DREMOVE fns ADVISEFNS) ) ) 
(SETQ fns.1 when) 
loop 
(SELECTQ fns.1 
(NIL 
(* 
Advise[<function)] implies 
setting up for advising and 
exiting 


) 
(RETURN fns) ) 
(BEFORE 
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(SETQ fns.2 
(CDDR 
(CADDR 
(CADDR fns.2))))) 
(AFTER 
(SETQ fns.2 (CDDDR fns.2) ) 
( AROUND 
(SETQ fns.2 
(CAR 
(LAST (CADDR (CADDR 
fns.2))))) 
(COND 
((NEQ (CAR fns.2) 'ADV-RETURN) 
(ERROR "ADVISE" when '?) 
(RETURN) ) ) 
(RPLACA (CDR fns.2) 
(SUBPAIR' * 
(LIST (CADR fns.2 
what) ))) 
(GO exit)) 
(BIND 
(NCONC (CADR fns.2) 
(COND 
((ATOM what) 
(LIST what) ) 
(T 
(APPEND what) ) )) 
(GO exit) ) 
(ERROR "ADVISE" when '?)) 
(COND 
((NULL where) 
(ATTACH what (LAST fns .2))) 
(T 
(ADD.ADVICE fns.2 what where T))) 
exit 
(ADDPROP fns 'ADVICE (LIST when where what) ) 
(RETURN fns) ) 


)) 


where the subfunctions are defined as follows: 


(DEFINEQ 


(advise1 (fns.1 fns.2 a.flag) 
(PROG (fns.3) 
(COND 
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((NOT (ATOM fns.3)) 
(RETURN fns.3)) 
(a.flag 
(advise fns.3 (COPY when) 
(COPY where) 
(COPY what) )) 
(T 
(advise fns.3 when where what) )) 
(RETURN fns.3)) 
)) 


(DEFINEQ 
(advise2 (a.fns.2) 
(advise fns.1 a.fns.2 T) 
)) 


(DEFINEQ 
(advise3 (a.fns) 
(advise1 a.fns when T) 
)) 


(DEFINEQ 
(advise4 (a.fns) 
(MAPCAR fns.2 (FUNCTION advise41) ) 
)) 


(DEFINEQ 
(advise41 (a.fns.2) 
(advisel a.fns a.fns.2 T) 
)) 


(DEFINEQ 
(advised (a.fns) 
(advise a.fns (COPY when) (COPY where) (COPY 
what) ) 


)) 
21.2 UNADVISE: REMOVING ADVICE 


You may remove advice from a function by executing UNADVISE, which takes 
the form 


Function: UNADVISE 

# Arguments: 1 

Arguments: 1) an expression, EXPRESSION 

Value: A list of the functions that have been 


unadvised. 
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UNADVISE is an NLAMBDA, nospread function. For each function found 
in EXPRESSION, UNADVISE removes the properties created by ADVISE as 
well as any program code added to the body of the function that was specified by 
ADVISE. 

UNADVISE will save on the list ADVINFOLST enough information to al- 
low you to READVISE a function at a later time. 

UNADVISE, when executed with no arguments, unadvises all functions 
that are described on ADVISEDFNS. It sets ADVINFOLST to NIL. 

UNADVISE, when executed with an argument of T, unadvises the first 
function on ADVISEDENS. That is, it unadvises the last (most recent) function 
that was advised. 


21.3 READVISING A FUNCTION 


You may restore a function to its advised state by executing READVISE. 
READVISE uses information found on ADVINFOLST or under the property 
READVICE to reinstate the advice for the specified functions. It takes the form 


Function: READVISE 

# Arguments: 1 

Arguments: 1) an expression, EXPRESSION 

Value: A list of functions that have been 
readvised. 


READVISE is an NLAMBDA, nospread function. If you readvise a func- 
tion, the advice will be stored under the property READVICE on the atom’s 
property list. Thus, you may advise a function once, then unadvise and readvise 
it many times without having to specify all of the original information. 

READVISE, when executed with no arguments, will readvise every function 
that is found on ADVINFOLST. Thus, you can turn advising on and off for a 
large number of functions with a simple function invocation. 


21.4 SAVING ADVICE IN A FILE 


As noted in Section 17.2.10, the File Package provides a file package command 
for saving advice for functions between sessions. PRETTYDEF creates the 
proper entries in a file to readvise the functions saved in the file when it is re- 
loaded. It uses ADVISEDUMP to place the proper information in the file. AD- 
VISEDUMP takes the form 
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Function: ADVISEDUMP 
# Arguments: 2 
Arguments: 1) a function, FNS 
2) a flag, FLAG 
Value: A list of the functions dumped. 


If FLAG is T, ADVISEDUMP writes two expressions to the primary output 
file: a DEFLIST expression and a READVISE expression. However, if FLAG is 
NIL, only the DEFLIST expression is written to the file. The difference is that 
the former corresponds to the action of readvising a function while the latter 
corresponds to the process of advising. In either case, the advice is copied to the 
property READVICE of the function which makes it ‘‘permanent”’ since all 
properties and their values will also be dumped to the file. 


A Definition of ADVISEDUMP 
We might define ADVISEDUMP as follows: 


(DEFINEQ 
(advisedump (fns flag) 
(* 
FLAG is T for READVISE and NIL for ADVISE. 


) 
(SETQ fns 

(MAPCONC fns 

(FUNCTION advise.dump.1))) 

(MAKEDEFLIST fns 'READVICE) 
(COND 

(flag 

(PRINTDEF (CONS 'READVISE fns)))) 
)) 


(DEFINEQ 
(advise.dump.1 (fn) 
(MAPCAR (PACK-IN- fn) 
(FUNCTION advise.dump.2) ) 


)) 


(DEFINEQ 
(advise.dump.2 (fn) 
(PROG (property-list) 
(SETQ property-list (GETPROP fn 'ADVICE)) 
(COND 
(property-list 
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(PUTPROP fn 
"READVICE 
(CONS (GETPROP fn 'ALIAS) 
(APPEND property- 
list))))) 
(RETURN fn) ) 
)) 
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DWIM: Automatic Error 
Correction 


DWIM means Do- What-I-Mean. It is an automatic error correction facility that 
assists you in correcting errors that do not affect the structure or logic of your 
program. Many of the errors made by INTERLISP programmers are simple 
ones that are easily recognized and fixed, so much so that another program 
could watch what you type in or inspect a program as it is read from a file and 
correct these errors. DWIM is a program that performs this function although 
(as the IRM notes) it only operates on unbound atoms and undefined functions 
at the present time. When an error occurs, DWIM inspects the current context 
of the computation, attempts to figure out what is wrong and how it may be 
corrected, attempts to correct it (possibly with confirmation), and lets the com- 
putation proceed as if no error had occurred. 


‘ 


22.1 DWIM MODES 


DWIM can operate in one of three modes: disabled, cautious, or trusting. 

When DWIM is disabled, it will not interfere with your activities. DWIM 
may be disabled by executing (DWIM NIL) or setting DWIMFLG to NIL. 

In cautious mode, DWIM determines what correction is to be applied, if 
any, and then seeks approval from you. You may answer YES or NO to any 
suggested correction. DWIM uses an internal interval timer to determine how 
long to wait for a user response. If the interval expires, DWIM proceeds auto- 
matically with the correction. DWIM may be placed in cautious mode by execut- 
ing (DWIM ‘C). This is also the initial setting of DWIM when it is first loaded. 

DWIM may also be placed in trusting mode. In this mode, DWIM performs 
the appropriate corrections without requiring you to approve them. DWIM may 
be placed in trusting mode by executing (DWIM ‘T). 

When DWIM makes a correction, it is contained only within the current 
image of the program, e.g., the virtual memory. To preserve the correction, the 
user will have to execute MAKEFILE to update the disk-based version of the 


program. 
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22.1.1 A DWIM Example 


Consider a function that you have entered from a file via LOAD. 


(* COPYLIST-makes a copy of its argument *) 
(DEFINEQ 
(copylist (x) 
(COND 
((NULL x) NIL) 
((LIST-P x) 
(APEND (LIST (copylist (CAR x))) 
(copylst (CDR x)))) 
(T x)) 


)) 


Let us assume that DWIM currently operates in cautious mode. We can 
execute COPYLIST as follows: 


+(SETQ x '(a b)) 
(A B) 


<(SETQ y (copylist x)) 


There are obvious errors of spelling in the definition of COPYLIST. DWIM 
detects these errors and responds: 


LIST-P [in COPYLIST] — LISTP? ...Yes 
APEND [in COPYLIST] — APPEND? ...Yes 
COPYLST [in COPYLIST] — COPYLIST? ...Yes 
(A B) 


In this case, the default answer is YES and the corrections have been ap- 
plied. Once all errors are corrected, INTERLISP calculates the value of the 
function. 

In trusting mode, when a function is already defined via LOAD or the edi- 
tor, DWIM operates as in cautious mode. However, when expressions are in- 
teractively entered via LISPX (see Section 25.2), DWIM makes the correction 
and tells you what it did. If you were to type in 


«(SEQT fruits (NCOCN ‘apples 'oranges) ) 
=SETQ 

=NCONC 

ORANGES 


would be the response from INTERLISP where DWIM interceded to correct the 
spellings of SETQ and NCONC. 
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22.2 DWIM PROTOCOLS 


A protocol is an interchange between DWIM and the user concerning actions to 
be taken to correct errors. Currently, DWIM corrects three types of errors: 


1. Spelling errors 
2. Parenthesis Typing Errors 
3. T Clause Errors 


22.2.1 Spelling Correction 


Whenever INTERLISP encounters a function or an atom it does not recognize, * 
it invokes DWIM (if DWIMFLG is not NIL) to see if spelling correction is re- 
quired. If the error did not occur in type-in mode, DWIM displays the following 
message (see example above): 


<name>) [in <function-name)] — corrected name)? 


DWIM proceeds based on the value of APPROVEFLG. If APPROVEFLG 
is NIL, DWIM makes the correction and continues. Otherwise, it waits for your 
response. This response takes one of the following forms: 


Y whence DWIM echoes es and makes the correction. 

N whence DWIM echoes o and does not make the correction. 

tT whence DWIM does not make the correction and does not cause an error. 
CNTRL-E whence DWIM prints U.D.F. and forces a break. 

Do nothing, whence DWIM waits a specified interval and then types ... 
followed by the default answer (e.g., the value of FIXSPELLDEFAULT). 
<SP) or (CR) whence DWIM waits indefinitely. 


Note that when you type N, you are instructing DWIM’s spelling corrector 
to return NIL. This lets the function decide what to do next. 


Modifying the Wait Interval 

The interval for which DWIM will wait for your response is specified by DWIM- 
WAIT. Initially, the value of DWIMWAIT is 10 seconds. You may reset the 
value of DWIMWAIT to meet your own requirements. Setting DWIMWAIT to 
100 provides you (roughly) one and a half minutes to think about your answer. 
Setting DWIMWAIT to an arbitrarily large number () 10000) should provide 
you enough time to mull over the problem and formulate a response. Setting 
DWIMWAIT to 0 causes DWIM to take the default immediately. 


Modifying the Spelling Default 

After the wait interval has expired and you have not responded, DWIM will 
substitute the default answer and continue. The default answer is specified by 
FIXSPELLDEFAULT. Its initial value is Y(es). You may reset it via 
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*-(SETQ FIXSPELLDEFAULT 'N) 
N 


22.2.2 Parenthesis Errors — 


A typical error that results when you are entering a large program is to substitute 
a “9” for a “(' or a “0” for a'")”. This results from failure to push the SHIFT 
key (on the Xerox 1100 keyboard). DWIM recognizes when such errors occur 
and corrects them in a manner similar to spelling correction. 


+(SETQ states 9LIST 'maryland 'virginia 'newyork) ) 
= ( LIST 
(maryland virginia newyork) 


where DWIM has detected the parenthesis error and corrected it. 

Unfortunately, ‘("' and "')”’ often occur over other keys than ‘9’ or “0” on 
other keyboards. There is no mechanism for specifying the relationship between 
the parentheses (left or right) and the erroneous keys. Thus, DWIM fails to work 
in some cases for foreign terminals. 

When DWIM attempts to correct a parenthesis error, it waits for 3*DWIM- 
WAIT seconds. This allows you time to consider the expression and, perhaps, 
back up over the last parenthesis and continue typing. 


22.2.3 Clause Errors 


A clause error occurs when a (T ...) clause is misplaced within a conditional 
expression. If uncorrected, INTERLISP treats the T clause as a function invoca- 
tion, does not recognize T as a function, and responds with a U.D.F. error. 
DWIM recognizes and corrects three cases of this error: 


1. The T clause appears outside the conditional expression. A previous 
clause is entered with an additional right parenthesis which completes 
the conditional expression. 


(COND 
((ATOM x) ...) 
(CL ISTP SB) ute 3) 
((STRINGP x) ...)) ‘ extraneous parenthesis 


CP saad) 


where the ... means we don’t care what follows. 


2. The T clause appears within a previous conditional clause. A right pa- 
renthesis is omitted from a previous conditional clause. 
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(COND 
((ATOM x) ...) 
((LISTP x) eet 
((STRINGP x) ... & < missing parenthesis 
CP 5a ab) 


3. A T clause is surrounded by an additional pair of parentheses. Gener- 
ally, this is a typing error resulting from a psychological mistake, e.g. 
following a pattern for creating conditional clauses in the expression. 


(COND 
((ATOM x) ...) 
((LISTP x) ...) 
((STRINGP x) ...) 
ab aren by 


Any other type of U.D.F. error is not currently recognized by 
DWIM, so the error will cause a break. 


Fixing the Error 
DWIM automatically corrects a T clause error on type-in. It prints T FIXED 
and continues. 

If APPROVEFLG is NIL, DWIM corrects the error and prints a message 
consisting of [IN <function name)] followed by one of the incorrect COND 
forms and —. On the following line, DWIM prints the correct COND form and 
proceeds. 


< (DEFINEQ 
(FACT (n) 
(COND 
((ZEROP n) 1)) 
(T 
(ITIMES n 
(FACT (SUB1 n))))) 
)) 
(FACT) 
«(SETQ APPROVEFLG NIL) 
NIL 
«(FACT 3) 


[IN FACT] (COND ...) (T...) -) 
(COND: cc fT oso }) 
6 


If APPROVEEFLG is T, DWIM prints U.D.F. T followed by [IN <function 
name)], a few spaces, and FIX?. DWIM waits for approval (unless DWIM- 
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WAIT is exceeded). An answer of Y allows DWIM to proceed as if AP- 
PROVEFLG had a value of NIL. 


+-(SETQ APPROVEFLG 'T) 


T 
(FACT 3) 
U.D.F. T [IN FACT] FIX? Y "typed by the user" 


ACOND 'o05 ADs. v0)) 
CONTINUE WITH T CLAUSE? Y 
6 


Proceeding with the Computation 
Once DWIM makes a correction, it must decide how to proceed with the compu- 
tation. Each of three cases is treated separately. 

When the T clause is outside the COND expression (case 1), DWIM cannot 
know whether the last clause of the COND succeeded or not. That is, if the T 
clause were enclosed within the COND expression, would it have been executed? 
Thus, DWIM will ask you whether or not it should continue with the T clause 
(see example above). The default answer is YES. If you answer NO, DWIM 
proceeds to execute the expression following the (previously) erroneous T clause. 

When the T clause is embedded in the previous clause (case 2), DWIM 
moves the T clause to its proper place in the COND expression. The T clause was 
reached through successful execution of & (see case above). The value of & must 
be returned as the value of the COND expression, but this value is no longer 
around. Therefore, DWIM asks you “OK TO REEVALUATE” followed by the 
expression corresponding to &. If you respond Y, DWIM reevaluates & and 
proceeds. Otherwise, DWIM aborts the computation, prints U.D.F. T, and 
causes an error. 

Before requesting your approval, DWIM determines whether or not it is safe 
to reevaluate the form. It will do so without commenting if the form is atomic or 
if the CAR of each of its sublists appears on OKREEVALST and each of the 
arguments can safely be reevaluated. The initial value of OKREEVALST is 


<-OKREEVALST 
(AND OR PROGN SAVESETQ CAR CDR ADD1 SUB1 CONS LIST BQ 
EQUAL PRINT PRIN1 APPEND NEQ NOT NULL) 


When the T clause is surrounded by an extra pair of parentheses, DWIM 
merely removes them and proceeds with the computation. 


22.3 ERROR CORRECTION ALGORITHMS 


Whenever INTERLISP encounters an S-expression whose first atomic form has 
no binding (that is, no current value), it invokes FAULTEVAL. If DWIM is 
enabled, DWIMBLOCK is called by FAULTEVAL to attempt to treat the error. 
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DWIMBLOCK determines what correction is to be made, if any, and dis- 
plays it for you. If you disapprove of the correction by entering N, CNTRL-E, or 
tT, DWIMBLOCK returns NIL and allows FAULTEVAL to handle the error. If 
DWIM is allowed to correct the error, it returns the corrected value (via RE- 
TEVAL—see Section 30.8.3) to FAULTEVAL. In this case, FAULTEVAL 
assumes the returned value is an erroneous form and attempts to execute it. 
However, since the form is now corrected, it will execute properly and the com- 
putation will proceed. 

DWIM can correct three types of errors: unbound atoms, undefined func- 
tions (represented by the CARs of functional forms), and undefined functions 
which are the arguments of APPLY. Algorithms for correcting these three error 
types are discussed in the next three sections. 


22.3.1 Unbound Atoms 


An unbound atom is one that has not been assigned a value (even though the 
value stored in its value cell is NOBIND). This error usually occurs when an 
atom name is used in an expression without previously being used in a SETQ or 
is defined in a PROG without being assigned a value. 

DWIM uses the following algorithm to attempt to correct an unbound 
atom: 


1. If the first character of the atomic form is ', DWIM assumes you in- 
tended to specify the form '{atom name). DWIM substitutes (QUOTE 
{atom name)) and proceeds. If ' is followed by an S-expression, then 
DWIM assumes that you wanted the entire S-expression quoted. In ei- 
ther case, no message is displayed and your approval is not sought. If 
just the single character ' appears, DWIM gives up. 

However, the interpretation of ' on type-in is controlled by a read 
table (usually) and so '{atom name) will automatically be converted to 
(QUOTE atom name)). You may view how this operates by typing in 
the definition of a new function and then applying PP to it. Each 
'{atom name) will be replaced by (QUOTE (atom name)). 


<— (DEFINEQ 
(test.for.stop (argument) 
(EQUAL argument 'STOP) 


)) 
(TEST. FOR.STOP) 


«(PP TEST. FOR.STOP) 
(TEST. FOR.STOP 
(LAMBDA (argument) 
(EQUAL argument (QUOTE STOP) ))) 
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2. If CLISP is enabled (see Chapter 23), DWIM determines if the atom is 


part of a CLISP construct. If so, the appropriate transformation is ap- 
plied and returned. 


. If. an atom contains a ‘‘9"’, DWIM assumes that you intended it to be a 


“(’. It calls the editor to repair the expression containing the atom. 
DWIM attempts to repair the entire expression by balancing parenthe- 
ses. 

Note that a form like 


(LIST x9CAR y) becomes (LIST x (CAR y)) 


where the parentheses have been Delanten after the 9 has been replaced 
by a(. 

Note that this feature does not work if “(’”’ is the shift character for 
another key. For example, on my Lear-Siegler ADM-3A, the ‘‘(’’ is the 
shift character for “8”. There is no way to tell DWIM how to treat these 
kinds of terminals. 


. A similar action takes place if an atom contains a “0” except that the 


replacement is a ‘‘)’’. 


Note that other terminals may have the “‘)” as the shift character 
for the “‘9”’. There is no way to tell DWIM how to handle this case. 


. If an atom begins with a 7 (on TTY-type keyboards), DWIM assumes 


you intended to type ‘ and performs the replacement. 


<(SETQ super.bowl.XVIII 7los.angeles.raiders) 
los.angeles.raiders 


<super.bowl.XxVIII 
los.angeles.raiders 


Note that certain keyboards, like the ADDS Viewpoint, have the " 
as the SHIFT value of the ' key. DWIM assumes that a "' is a valid 
demarcator for a string in this case and cannot correct an atom error. 


. If the atom is a valid Editor command, DWIM assumes that you in- 


tended to call the Editor. It does so (by invoking EDITF), and executes 
the command. At this point, you are in the Editor and must follow its 
conventions. Valid edit commands are stored on the Editor variable 
EDITCOMSA. 


. DWIM looks on DWIMUSERFORMS for S-expressions. It evaluates 


each one in turn. If a non-NIL value is returned, this value is returned 
by DWIMBLOCK as the corrected value of the atom. DWIMUSER- 
FORMS allows you to tailor DWIM’s error correction algorithm to spe- 
cific users. Words which are difficult to spell might be intercepted by 
expressions on DWIMUSERFORMS and corrected. In general, it will 





10. 


11. 
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be quicker to correct a word through expressions on DWIMUSER- 
FORMS than through the spelling corrector. Section 22.7.1 describes 
the parameters to be used in writing these expressions. 


- If the unbound atom occurs in a function, DWIM attempts to correct 


the spelling of the atom using the LAMBDA and PROG variables (if 
any) of the function. Here DWIM assumes that the atom may be a valid 
variable whose name is misspelled. 


. If the unbound atom was entered in response to a broken function, 


DWIM attempts to correct spelling using the LAMBDA and PROG 
variables of the broken function. 


Finally, DWIM will attempt to correct the spelling of the atom name 
using SPELLINGS3 (see Section 22.7.2). 


Otherwise, DWIM fails. 


22.3.2 Undefined Functions 


Properly, this error is known as an “undefined CAR of form.’’ However, this 
error typically occurs when an atom appears as the first atom of an S-expression 
without a corresponding function definition. 

DWIM uses the following algorithm to attempt to correct this error: 


1. 


2. 


If the ATOM is T, DWIM assumes a misplaced T clause and attempts 
to correct the conditional (see Section 22.2.3). 

If the atom is F/L, DWIM replaces F/L with FUNCTION (LAMBDA 
and proceeds. 

Note F/L is a shorthand notation for specifying the form ‘‘“FUNC- 
TION (LAMBDA”’. DWIM will look for a variable list by determining 
how many S-expressions follow the F/L. If only one appears, DWIM 
substitutes (x) as the variable list. 


<(F/L (ADD1 x)) 
(LAMBDA (X) (ADD1 x)) 


because only one S-expression follows F/L. 
F/L is used only as a DWIM construct. Because it limits the porta- 
bility of your code, we do not recommend its use. 


. If the atom is IF or another CLISP statement operator, the appropriate 


CLISP transformation is perfomed and the result returned to 
FAULTEVAL. 


. If the atom has a function definition, DWIM attempts spelling correc- 


tion on the CAR of the definition using the value of LAMBDASPLST. 
LAMBDASPLST initially has the value (LAMBDA NLAMBDA). 
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5. If the atom has an EXPR or CODE property, DWIM prints (atom 
name) UNSAVED, executes UNSAVEDFEF to restore the definition to 
the function cell, and continues. No approval is requested. 

6. If the atom has the property FILEDEF, its definition is to be found in a 
file. DWIM looks for the definition. If it is found, DWIM asks you if it 
should be loaded. If you approve, the definition is loaded and execution 
proceeds. 


-(LOADFROM 'COMPLEX) 
{KAISLER) COMPLEX. .4 


<-(PUTPROP 'CMULT 'FILEDEF 'COMPLEX) 
COMPLEX 


<—(DWIM 'T) 
TRUSTING 


«-(LOADFNS 'COMPLEX 'COMPLEX) 
(COMPLEX) 


<(SETQ CX1 (COMPLEX 3.0 4.0)) 
loading from <KAISLER)COMPLEX. .4 
PRINT. COMPLEX 

loading from <KAISLER)COMPLEX. .4 
REAL 

loading from <KAISLER)COMPLEX. .4 
IMAG 

((3.0 . 4.0)) 


<(CMULT CX1 CX2) 

loading from «KAISLER)COMPLEX. .4 
CMULT 

UNBOUND ATOM 

CX2 


7. If the atom is a CLISP construct and CLISP is enabled, the appropriate 
transformation is applied and execution continues. 

8. If the atom contains an 9, DWIM assumes a ( was intended, performs 
the substitution, and continues. 

9. Similarly, if the atom contains a 0, DWIM assumes a ) was intended, 
performs the substitution, and continues. 

10. If the CAR of the form is a list, DWIM attempts to correct the spelling 

of the CAAR of the form (e.g., the CAR of the list) using LAMBDASP- 
LST. If successful, DWIM returns the corrected expression. 


((LAMBDA (X) (SELECTQ X (...))) ..-) 
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may be a form that selects and returns a function name to be applied to 
the remaining arguments. If the LAMBDA is misspelled, using LAMB- 
DASPLST, DWIM corrects it. 


+ ((LAMBD (x) (ADD1 x))) 
=LAMBDA 

NON-NUMERIC ARG 

NIL 


11. If the error occurred in typein mode, and the CAR is a small number, 
DWIM assumes it is an edit command, invokes the Editor (via EDITF), 
and executes the command. 


(3) 

=CMULT ‘last function loaded' 
edit 

*% 


12. If the CAR of the form is an Editor command, DWIM invokes the edi- 
tor (via EDITF) and executes the command. 


#=(R XY) 

=CMULT 

edit 

X ? ‘deliberate error for illustration' 
x 


Note that the result of applying either case 11 or 12 is that the user 
remains within the Editor and is subject to its conventions. 

13. DWIM evaluates the expressions on DWIMUSERFORMS. If any S- 
expression returns a non-NIL value, this value is treated as the cor- 
rected form, it is evaluated and its value returned by DWIM. 

14. DWIM attempts spelling correction using SPELLINGS2 (see Section 
22.7.2). 

15. Otherwise, DWIM fails. 


22.3.3 Undefined Functions in APPLY 


An undefined function occurring as an argument to APPLY is treated in a man- 
ner similar to an undefined CAR of form. The major difference is that DWIM 
will also attempt spelling correction using SPELLINGS1. 
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22.4 ENABLING DWIM 


DWIM enables or disables automatic error correction. It takes the following 
form 


Function: DWIM 


# Arguments: 1 
Argument: 1) a mode, MODE 
Value: The old mode. 


MODE may take one of the following values to specify how DWIM will op- 
erate: 


1. If MODE is NIL, automatic error correction is disabled. 
2. If MODE is C, DWIM is enabled in cautious mode. 


<(DWIM 'C) 
CAUTIOUS 


3. If MODE is T, DWIM is enabled in trusting mode. 


<(DWIM 'T) 
TRUSTING 


4. All other values cause an error. 


<—(DWIM 'X) 
not on DWIMODELST. 


DWIMODELST is a list of the modes that DWIM recognizes as valid: 


<-DWIMODELST 
((C CAUTIOUS (APPROVEFLG . T)) (T TRUSTING 
(APPROVEFLG) ) ) 


During type-in mode, DWIM always acts as if it were in TRUSTING 
mode when expressions are submitted for execution. Errors involving 8-9 
correction or spelling correction are always treated as if DWIM were in 
CAUTIOUS mode. 


22.5 DWIMIFYING AN EXPRESSION 


DWIMIFY acts as a preprocessor for CLISP. It scans an expression given to it as 
though it were being interpreted. For each expression that would generate an 
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error, it calls DWIM to fix it. You are consulted (for your approval) when some- 
thing in the expression is to be corrected. If DWIM is unable to make the correc- 
tion, no message is printed, and no changes are made. 

DWIMIFY performs all corrections and transformations to its first argu- 
ment that would actually occur if it were run. It takes the form 


Function: DWIMIFY 
# Arguments: 3 


Arguments: 1) a form or function name, EXPRESSION 
2) a quiet flag, QUIETFLG 
3) a list, LST 


Value: Either the result or nothing. 


EXPRESSION is an expression to be DWIMIFYed. If EXPRESSION is an 
atom and LST is NIL, then DWIMIFY assumes that EXPRESSION is the name 
of a function and DWIMIFYs its definition. The result is printed unless 
QUIETFEFLG is T. 

If EXPRESSION is a list or LST is non-NIL, EXPRESSION is an expres- 
sion to be DWIMIFYed. If LST is not NIL, it provides an edit push-down list 
leading to EXPRESSION that describes the context of EXPRESSION so that 
variable bindings may be determined. This form is primarily used for invoking 
DWIMIFY from the Editor, the Break Package, and the Programmer’s Assis- 
tant. 

Consider the following examples: 


«(DWIMIFY '(LAMBD (X) (ADD3 X))) 
=LAMBDA 
(LAMBDA (X) 
(ADD3 X)) 
(LAMBDA (X) (ADD3 X)) 


<(DWIMIFY '(CONS (QUOTE SEAN CONNERY) )) 
(possible) parenthesis error in 

(QUOTE SEAN CONNERY) 

too many arguments (more than 1) 

(CONS (QUOTE SEAN CONNERY) ) 


When an attempt to correct a function or variable fails, the name is added to 
a corresponding internal list. On subsequent encounters, DWIMIFY will not 
attempt to operate on names appearing on either of these lists. These lists are 
initialized to NOFIXFNSLST and NOFIXVARLST respectively. 

DWIMIFY never attempts corrections on global variables in order to avoid 
affecting the operation of other portions of your program. Similarly, no attempt 
will be made to correct variables which are defined: 
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as LOCALFREEVARS in block declarations 
as SPECVARS in block declarations 
via DECLARE expressions in the function body 


In order to work properly, DWIMIFY needs a lot of information about how 
the interpreter works. Among the “things” that it knows are 


The systax of various expressions 
NLAMBDA arguments are not evaluated 
How variables are to be bound 


When to correct or not correct the spelling of variables occurring in the 
expression 


How to correct errors for CAR of expressions 


When an expression has too many arguments, which are symptomatic of 
parenthesis errors 


If PROG labels contain CLISP characters 


Note: DWIM has not evolved very much from its initial development. This is 
unfortunate because the concept is a powerful one. Do not expect DWIM to 
operate correctly in every case; it operates unevenly at best. 


22.5.1 DWIMIFYing a List of Functions 


An alternative form of DWIMIFY, DWIMIFYFNS, DWIMIFYes each func- 
tion on its argument list. It takes the form 


Function: DWIMIFYFNS 

# Arguments: 1 

Argument: 1) A list of functions, FNSLST 

Value: The list of functions that have been 
DWIMIFYed. 


DWIMIFYENS is an NLAMBDA, nospread function. If the CAR of 
FNSLST is atomic, it is assumed to be the name of a file whose functions are to 
be DWIMIFYed. If so, DWIMIFYFNS invokes FILEFNSLST (see Section 
17.7.3) on the CAR of FNSLST. The file must already be loaded for DWIMI- 
FYFNS to operate properly. 


«-(LOADFROM 'COMPLEX) 
{KAISLER) COMPLEX. .4 


<— (DWIMIFYFNS COMPLEX) 
CPLUS not defined. 
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(LOAD 'COMPLEX) 

{KAISLER) COMPLEX. .4 

FILE CREATED 17-Oct-84 21:20:25 
COMPLEXCOMS 

<KAISLER) COMPLEX. .4 


<(DWIMIFYFNS COMPLEX) 

[in ROUNDTO] (possible) parenthesis error in 
(ROUNDED (QUOTIENT X ¥} ¥) 

too many arguments (more than 1) 

(COMPLEX REAL IMAG CPLUS CDIFFERENCE CZERO CMULT 
PRINT.COMPLEX FLOOR ROUNDTO SIGN ROUNDED RECIPROCAL 
TRUNCATE PRINT.ARRAY FACTORIAL) 


DWIM discovered an error in ROUNDTO because ROUNDED expects 
only one argument, as evidenced by the following display: 


«(PP ROUNDED) 
(ROUNDED 
(LAMBDA (X) **COMMENT** 
(TRUNCATE (PLUS X (QUOTIENT (SIGN X) 
2.0))))) 


which we correct via the Editor. Thus, DWIMIFYing functions in a file is one 
way of locating errors. 


22.5.2 DWIMIFY Variables 


DWIMIFY uses a number of variables to determine how it should proceed with 
the different situations it encounters in an expression. These variables are 


NOFIXVARSLST A list of variables that DWIMIFY 
will not try to correct. You may 
use this list to prevent DWIMIFY 
from expending needless effort 
on correcting variable 
spellings. 


NOFIXFNSLST A list of functions that DWIMIFY 
will not try to correct (for the 
same reason as above). 


NOSPELLFLG If NOSPELLFLG is T, DWIMIFY will 
not perform any spelling 
correction. Its initial value is 
NIL. NOSPELLFLG is reset to T 
when the compiler is called to 
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compile functions whose 
definitions are loaded from a 
file. For example, 


<(SETQ NOSPELLFLG T) 
(NOSPELLFLG reset) 


8 
<(DWIMIFY '(LAMBD (X) (ADD3 X))) 
(LAMBD (X) 
(ADD3 X)) 
DWIMIFYCOMPFLG If T, DWIMIFY is called before 
an expression is compiled. 
DWIMCHECK#ARGSFLG If T, DWIMIFY will check whether 


or not the expression, whose CAR 
is assumed to be a function 
name, has arguments. Its value 
is initially T. Consider the 
example 


<(SETQ DWIMCHECK#ARGSFLG NIL) 
(DWIMCHECK#ARGSFLG reset) 
NIL . 


<(DWIMIFY '(CONS (QUOTE SEAN CONNERY))) 
(CONS (QUOTE SEAN CONNERY)) 


where DWIM does not checks the 
argument count for QUOTE. 


DWIMCHECKPROGLABELSFLG If T, DWIMIFY will check PROG 
labels for CLISP characters. 


DWIMMESSGAG If T, DWIMIFY does not print any 
error messages. Its value is 
initially NIL. 


CLISPHELPFLG If NIL, DWIMIFY will not ask you 
to approve any CLISP 
translations that it makes. 
Rather, it assumes NO where your 
approval would be required. Its 
value is initially T. 


CLISPRETRANFLG If T, DWIMIFY retranslates all 
expressions which have remote 
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translations in the CLISP hash 
array. Its value is initially 
NIL. 


22.6 THE SPELLING CORRECTOR 


The objective of the spelling corrector is to produce the correct word, called the 
respelling, given a word that is assumed to be incorrect. To do so, it uses a 
“‘closeness’”’ measure which is inversely proportional to the number of disagree- 
ments between two words—the word to be corrected, XWORD, and a candi- 
date—and directly proportional to the length of the longer word. The spelling 
corrector examines a spelling list, SPLST, provided by the user, from which it 
selects candidates. The closeness between XWORD and each candidate is com- 
puted. An internal list of closest candidates is generated and retained. 

If a word is found on SPLST for which there are no disagreements, the spell- 
ing corrrector returns that word as the respelling of XWORD. Alternatively, if it 
has found no disagreements and only one “‘closest’’ word, this word is returned 
as the respelling. 

XWORD may contain one or more (ESC)s. (ESC) will match any number 
of characters in a potential candidate. The entire spelling list is always searched. 
If more than one respelling is found, the spelling corrector prints “‘AMBIGU- 
OUS” and returns NIL. 

Each respelling, whether approved by you or not, is moved to the front of 
SPLST. Because many respellings have no disagreements, the time required to 
correct the spelling of frequently misspelled words is significantly reduced. 
These words appear at the beginning of the list which is searched from front to 
back, so they are likely to be found earlier when spelling correction is attempted. 

The spelling corrector counts the number of disagreements between two 
words. This number, when divided by the length of the longer of the two words, 
gives a measure of the relative disagreement between the two words. This num- 
ber is always less than or equal to one (where one indicates total disagreement!). 
One minus this number yields a measure of the relative agreement or closeness of 
the two words. (In practice, the spelling corrector uses integer values between 0 
and 100 in order to avoid the penalties of floating point arithmetic.) 

Consider the words MAKEFILE and MKAEFILE. They disagree in posi- 
tions 3 and 4 so the number of disagreements is 2. The length of both words is 8 
characters, so the measure of relative disagreement is 25 (e.g., (2/8)*100). 
Therefore, the measure of relative agreement is 75. 

The spelling corrector usually uses a relative agreement of 70. This allows it 
to correct single substitution errors in four character words. 


22.6.1 Choosing a Candidate 
CHOOZ is the central function of the spelling corrector. It takes the form 
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Function: CHOOZ 
# Arguments: 7 


Arguments: 1) a word to be corrected, XWORD 
2) a spelling list, SPLST 
3) a minimum relative agreement, REL 
4) a tail flag, TAIL 
5) an optional function, FN 
6) a tie flag, TIEFLAG 
7) number of doubled characters, DOUBLES 


Value: A list of possible candidates for the 
respelling. 


CHOOZ examines the spelling list one word, TWORD, at a time. TWORD 
is rejected as a candidate if: 


1. If FN returns NIL when applied to TWORD. 
2. It is too short or too long to be sufficiently close to XWORD. 


If REL is 70 and XWORD is five characters long, then words greater than 8 
characters in length will be rejected. Words shorter than XWORD require spe- 
cial consideration because doubled characters (due to keyboard stuttering or too 
much pressure on the keys) are not counted as disagreements. CHOOZ handles 
doubled characters in XWORD before scanning SPLST. CHOOZ uses the num- 
ber of doubled characters to decide whether or not to reject a word based on 
length. 

If TWORD is not rejected, CHOOZ computes the number of disagreements 
between TWORD and XWORD by calling SKOR (see below). 

FN is a function of one argument, TWORD. If FN is NIL, it is assumed 
equivalent to (LAMBDA NIL T) which means all words on SPLST are consid- 
ered as candidates. A simple definition for FN might compare its first character 
with that of XWORD (which it uses freely): 


(LAMBDA (tword) 


(EQ 
(CAR (UNPACK tword) ) 
(CAR (UNPACK xword)))) 
A Definition for CHOOZ 


We might define CHOOZ as follows: 


(DEFINEQ 
(chooz (xword rel splst tail fn tieflag doubles) 


(* 





22.6 The Spelling Corrector § 797 


Convert XWORD to a list of characters. 
(COND 
((NLISTP xword) 
(SETQ xword (CHCON xword)))) 
(PROG (xlength tlength tword twordlst synonym score 
value) 


(* 


) 
(SETQ xlength (LENGTH xword) ) 
(* 


Count the number of doubled characters. 
) 


(AND 
(NULL doubles) 
(SETQ doubles 0) 
(MAPCAR xword (FUNCTION count-doubles) ) ) 


Get the length of XWORD. 


loop 
(COND 
((NULL splst) 
(* 
If no candidates to inspect, do 
nothing. 


(GO exit.chooz) ) 
((NULL (SETQ tword (CAR splst))) 
(* 
Get next word on spelling list. Note 
that we check for end of spelling 
list via NULL. 


) 
(SETQ splst (CDR splst)) 
(GO loop) ) 
(T 
(SETQ splst (CDR splst)))) 
(COND 
((LISTP tword) 
(* 
If tword is a list, then the second 
element is a synonym for the first. 


) 

(SETQ synonym (CDR tword) ) 
(SETQ tword (CAR tword)))) 
(SETQ tlength (NCHARS tword) ) 
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(COND 
( (COND 
Sie tlength xlength) 
* 
Check to see if the 
difference in the number of 
characters between tword 
and xword is sufficient to 
make it unnecessary to call 
SKOR; xlength divided by 
tlength must be less than 
rel. 
) 
(ILESSP 
(IQUOTIENT (ITIMES xlength 
100) 
tlength) 
rel) ) 
((AND (NULL tail) 
(ILESSP 
( IQUOTIENT 
(ITIMES tlength 100) 
(IDIFFERENCE xlength 
doubles) ) 
rel) )) 
(* 
If XWORD is longer 
than TWORD, allow for 
the possibility of 
doubled characters. 


) 
(GO loop) ) 
( (AND 
(SETQ twordlst (chcon tword) ) 


(SETQ score 
(SKOR xword twordlst xlength 
tlength) ) 
(OR 
(NULL fn) 
(COND 
((EQUAL fn 'GETD) 
(* 


Get the definition of 
the comparison 
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function from the 
synonym. 


(GETD synonym) ) 
(T 
(APPLY* fn synonym) ) )) 
(SETQ twordlst 
(COND 
((LISTP tword) 
(* 


Distinguish from 
a runon 
correction which 
is returned as a 
dotted pair. 
) 
(LIST tword synonym) ) 
(T tword) ) ) 
(COND 
((LISTP score) 
(AND runonflg 
tail 
(OR 
(NULL value) 
(EQUAL tieflag 
'EVERYTHING) 
(IGREATERP tlength 
(NCHARS 
(CAAR 
value) ))) 
(SETQ value 
(CONS 
(CONS temp 
(PACKC 
score) ) 
(COND 
((EQ tieflag 
' EVERYTHING) 


value) )))) 
((ZEROP score) 


(COND 
((EQ tieflag 'EVERYTHING) 
(SETQ value 
(CONS temp 
value) )) 
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( (AND 
(NEQ tieflag 'ALL) 
tieflag 'LIST)) 
% 


Return the value. 


) 

(SETQ value temp) 

(RETURN value) ) 
(HER rel 100) 


Tieflag equal to LIST 
means list the tied 
candidates. 


) 
(SETQ rel 100) 
(SETQ value (LIST temp))) 


(T 
(SETQ value 
(CONS temp 
value) )))) 
( (IGREATERP 


(SETQ score 
(chooz1 xlength 
tlength 
score) ) 
rel) 
(SETQ value 
(CONS temp 
(COND 
((EQ tieflag 
' EVERYTHING) 
value) 
(T 
(SETQ rel 
score) 
NIL))))) 
((EQ score rel) 
(SETQ value 
(CONS twordlst 
value) ))))) 


(GO loop) 
exit.chooz 
(SETQ value 
(COND 
((OR 
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(EQ tieflag 'ALL) 
(EQ tieflag 'LIST) 
(EQ tieflag 'EVERYTHING) ) 
(COND | 
((CDR value) 
(REVERSE value) ) 
(T value) )) 
( (AND 
(CDR value) 
(NULL tieflag)) 
NIL) 
(T 
(CAR value) ))) 
(RETURN value) ) 
)) 


COUNT.DOUBLES merely counts the number of double characters in 
XWORD. It may be defined as: 


(DEFINEQ 
(count.doubles (x) 
(PROG (last.char) 
(SETQ last.char NIL) 
(COND 
((EQUAL x last.char) 
(SETQ doubles (ADD1 doubles) )) 
(T 
(SETQ last.char x)))) 
)) 


CHOOZ1 computes the relative closeness of XWORD and TWORD as a 
percentage by dividing the difference of the avergae number of characters and 
the number of mistakes. It is defined as 


(DEFINEQ 
(chooz1 (xlen tlen score) 

(PROG (temp) 

(SETQ temp (IPLUS xlen tlen) ) 

(RETURN 

(IQUOTIENT 
(ITIMES 100 
(IDIFFERENCE temp 
(ITIMES score 2))) 


temp) ) ) 
)) 
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22.6.2 Scoring a Candidate 


SKOR evaluates a candidate and computes the number of disagreements. It 
takes the form 


Function: SKOR 
# Arguments: 5 


Arguments: 1) the word to be corrected, XWORD 
2) a candidate word, TWORD , 
3) the length of XWORD, XLEN 
4) the length of TWORD, TLEN 
5) a flag, FLAG 


Value: The number of disagreements or NIL. 


SKOR scans both TWORD and XWORD from left to right one character 
code at a time. The list of character codes is prepared by CHOOZ before it calls 
SKOR. Corresponding characters agree if: 


1. They are, in fact, the same character. 
2. They appear on the same key of the keyboard; this handles the case of 
shift errors when typing characters in (see below). 


3. The character of XWORD is the lowercase version of the corresponding 
character of TWORD. 


Characters that agree are discarded. 

If the first characters of TWORD and XWORD do not agree, SKOR checks 
to see if either character is one that has already been encountered. In effect, 
transposition of characters is handled by looking back in the word rather than 
looking forward. Displacements of characters by two or fewer (e.g., when a char- 
acter is omitted in one word) positions are treated as a transposition error. Dis- 
placements of more than two positions are treated as disagreement errors. In 
either case, both characters have been accounted for and are discarded. 


When Characters Do Not Agree 
If the first characters do not agree and neither agrees with previously accounted 
for characters, SKOR operates as follows: 


1. If TWORD has more characters than XWORD remaining, the first 
character of TWORD is removed and saved, and comparison of 
TWORD with XWORD continues with the remaining characters. 

2. If TWORD has the same or fewer characters, the first character of 
XWORD is removed and saved, and comparison of TWORD with 
XWORD continues. However, a check is made to ensure that it is not a 
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double character typing error, whence the character would be considered 
accounted for. 


Whenever more than two characters in either XWORD or TWORD are un- 
accounted for, candidate scoring is aborted because the two words are consid- 
ered to disagree. 


Value Returned by SKOR 
When SKOR completes the comparison, it returns a value consisting of: 


1, The number of unaccounted-for characters, 
2. The number of disagreements, 
3. The number of transpositions. 


However, this number is subject to two qualifications: 


1. If both XWORD and TWORD have a character unaccounted-for in the 
same position, the two characters are counted only once. That is, substi- 
tution errors are counted as one disagreement. 

2. If there are no unaccounted-for characters and no disagreements, trans- 
positions are not counted. This permits spelling correction on very short 
words, such as editor commands (e.g., XRT becomes XTR). 


A Definition of SKOR 
We might define SKOR as follows: 


(DEFINEQ 
(skor (xword tword xlength tlength flag) 
(PROG (xbuf1 xbuf2 tbufl tbuf2 xfirst tfirst 
xchar index transpositions) 
(* 
Initialize SKOR variables. 
INDEX is the current position in the word. 
TRANSPOSITIONS counts the number of transposed 
characters. 


) 
(SETQ index 0) 
(SETQ transpositions 0) 


(* 


loop 


Get the first characters of XWORD and TWORD. 


) 
(SETQ xfirst (CAR xword) ) 
(SETQ tfirst (CAR tword) ) 
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(COND 
((NULL xword) 
(COND 
((NULL tword) 
(* 


If word to be corrected and 
candidates are both null, 
just exit. 


) 
(GO exit.skor) ) 
(T (GO loop2)))) 
((NULL tword) 
(GO loop1) ) 
((OR 
(EQUAL xfirst tfirst) 
(* 
Test for upper to lower case 
substitution. 
) 
( AND 
(EQUAL xfirst (IPLUS tfirst -64)) 
(IGREATERP xfirst 128) 
(ILESSP xfirst 170)) 
(AND 
(EQUAL tfirst (IPLUS xfirst -64)) 
(IGREATERP tfirst 128) 
(ILESSP tfirst 170) ) 
(* 
Check for user typing L instead of 1; 
the IRM being difficult to read. 
) 
(AND 
(EQUAL tfirst 241) 
(EQUAL xfirst 211))) 
(SETQ xword (CDR xword) ) 
(subivar xlength) 
(SETQ tword (CDR tword) ) 
(subivar tlength) 
(SETQ xchar xfirst) 
(GO loop) )) 
loop1 
(COND 
((EQUAL xfirst (CAR tbuf2)) 
(* 
A character has been encountered in 
TWORD before it has been seen in 
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XWORD. For example, the P in IPRNT 
compared to the P in PRINT. Note that 
RPINT is handled as a transposition 
of PRINT without consulting the 
buffers. 
) 
(COND 
((IGREATERP (LENGTH tbuf2) 
(IPLUS xlength 2)) 
(addivar index) ) 
(tT 
(addivar transpositions) )) 
(SETQ tbuf2 NIL) 
(SETQ xword (CDR xword) ) 
(sublvar xlength) 
(SETQ xchar (CAR tbuf1)) 
(GO loop) ) 
((EQUAL xfirst (CAR tbufi)) 
(COND 
((IGREATERP (length tbuf1) 
(IPLUS xlength 2)) 
(addivar index) ) 
(T (addivar transpositions) )) 


(COND 
(tbuf2 
(SETQ tbuf1 tbuf2) 
(SETQ tbuf2 NIL)) 
(T 


(SETQ tbuf1 NIL))) 
(SETQ xword (CDR xword)) 
(sublvar xlength) 
(SETQ xtemp xfirst) 
(GO loop) ) 
((NULL tword) 
(GO loop3))) 
loop2 
(COND 
((EQUAL tfirst (CAR xbuf2) ) 
(COND 
((IGREATERP (LENGTH xbuf2) 
(IPLUS tlength 2)) 
(addivar index) ) 
(T  (addivar transpositions) )) 
(SETQ xbuf2 NIL) 
(SETQ tword (CDR tword) ) 
(sublvar tlength) 
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(GO loop) ) 
((EQUAL tfirst (CAR xbuf1)) 
(COND 
((IGREATERP (LENGTH xbuf1) 
(IPLUS tlength 2)) 
(addivar index) ) 
(T (addivar transpositions) )) 


(COND 
(xbuf2 
(SETQ xbuf1 xbuf2) 
( (SETQ xbuf2 NIL) ) 
sy 


(SETQ xbuf1 NIL))) 

(SETQ tword (CDR tword) ) 

(sublvar tlength) 

(GO loop) ) 

((AND xword 

(EQUAL xfirst (CADR tword) ) 

(EQUAL tfirst (CADR xword) ) 

(NEQ tfirst (CADDR tword) )) 

(* 
Distinguish simple transposition from 
the case where comparison has become 
unsynchronized, e.g., MYCIN versus 
MICIN. If the Y is discarded, 
comparing CIN to ICIN looks like a 
transposition of CI (which is wrong) 
whereas it matches CI if the I is 
discarded. 


(SETQ xtemp (CADR xword) ) 
(SETQ xword (CDDR xword) ) 
(sublvar xlength) 
(subivar xlength) 
(addviar transpositions) 
(SETQ tword (CDDR tword) ) 
(subivar tlength) 
(sublvar tlength) 
(GO loop) ) 
((IGREATERP tlength xlength) 
(COND 
((NULL tbuf1) 
(SETQ tbuf1 tword) ) 
((NULL tbuf2) 
(SETQ tbuf2 tword) ) 
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(T (RETURN NIL))) 


(SETQ tword (CDR tword) ) 
(sublvar tlength) 
(GO loop) )) 


loop3 
(COND 
((OR 


(EQUAL xfirst xtemp) 
(EQUAL xfirst (CADR xword))) 


(* 


) 


Remove a character from XWORD. Check 
for a double character. First phrase 
checks if character is equal to last 
character which occurs when last 
character was correct. Second phrase 
checks if equal to next character, so 
throw the current one away. 


(SETQ xword (CDR xword) ) 
(SETQ xlengthgth (SUB1 xlength) ) 
(sublvar xlength) ) 
((AND tail 
(NULL tword) 
(NULL tbuf1) 
(NULL tbuf2) 
(NULL xbuf1) 
(NULL xbuf2) 
(ZEROP index) 


(OR 


(* 


) 


(ILESSP (ITIMES transpositions 4) 
tlength) 
(NULL (CDR xword) ))) 


Don't handle runon corrections when 
there is a transposition unless the 
word is very long. 


(RETURN 


(COND 
((AND flag 
CLISPFLG 
(MEMBER (CHARACTER (CAR 
xword) ) 
CLISPCHARS) ) 
(* 
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Do not consider runon 
corrections when 
encountering CLISP 
operators. If X*Y appears 
in your program, where X is 
bound, but Y is not, then 
DWIM should not offer X ¥*Y 
as a possibility. 
) 
NIL) 
(T xword)))) 
(T 
(COND 
((NULL xbuf1) 
(SETQ xbuf1 xword) ) 
((NULL xbuf2) 
(SETQ xbuf2 xword) ) 
(T (RETURN NIL))) 
(SETQ xword (CDR xword) ) 
(sublvar xlength) 
(SETQ xtemp xfirst))) 
(GO loop) 
exit.skor 
(COND 
( (AND 
(NULL xword) 
(NULL tword) 
tbuf1 
xbuf1) 
(SETQ tbufi (LENGTH tbuf1) ) 
(SETQ xbuf1 (LENGTH xbuf1) ) 
( AND 
tbuf2 
(SETQ tbuf2 (LENGTH tbuf2))) 
(AND xbuf2 
(SETQ xbuf2 (LENGTH xbuf2))) 
(COND 
((OR 
(EQUAL tbuf1 xbuf1) 
(EQUAL tbuf1 xbuf2) ) 
(* 
Check for substitution 
errors. Subtract 1 so when 
2 gets added below the net 
effect is 1. 





)) 
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(3 (sublvar index) )) 
ND 
( (AND 
tbuf2 
(OR 
(EQUAL tbuf2 xbuf1) 
(EQUAL tbuf2 xbuf2))) 
‘eine Re (sublvar index) )))) 
index 
(IPLUS index 
(COND 
(xbuf2 2) 
(xbuf1 1) 
(T 0)) 


(tbuf2 2) 
(tbuf1 1) 


(T 0)))) 
(RETURN 
(IPLUS index transpositions) ) ) 


(COND 


22.7 DWIM PARAMETERS 


DWIM uses several parameters to determine how it will perform automatic error 
correction (including spelling correction). These variables are described in the 
following table: 


DWIMFLG If NIL, suppresses all automatic 


error correction operations. It is 
initially NIL. This flag is set when 
you execute the function DWIM. 


FIXSPELLREL The default value for REL that is 


used by FIXSPELL when REL is NIL. It 
is initially 70. You may reset 
FIXSPELLREL to any value you want. 
Obviously, lower values will allow 
greater disagreement between the word 
to be checked and the candidate 
words. 


FIXSPELLDEFAULT The default answer when the user does 


not respond to a request for approval 
of a spelling correction. Its initial 
value is Y (for yes). When DWIMIFY is 


810 DWIM: Automatic Error Correction 


invoked, this variable is temporarily 
rebound to N (for no). 


DWIMWAIT The number of seconds that DWIM waits 
after requesting approval for some 
action. If the user does not respond 
within this time, DWIM assumes the 
default value (see discussion above). 


- ADDSPELLFLG If NIL, this flag suppresses calls to 
ADDSPELL (see Section 22.8.1). It is 
initially T. 


RUNONFLG If NIL, this flag suppresses any run- 

; on spelling corrections. It is 
initially T. A run-on condition 
occurs when two words are typed 
without an intervening space. Runons 
are difficult to detect, but CHOOZ 
can determine simple cases. 


DWIMUSERFORMS A list that allows you to specify 
your own corrections or 
transformations. Its initial value is 
((MACROTRAN) (DWIMLOADFNS?)). It is 
discussed in more detail below. 


DWIMLOADFNSFLG If T, DWIM loads a function from a 
file noticed by the File Package when 
it encounters an undefined function 
in some operation. It is initially T. 


APPROVEFLG If T, DWIM will ask you for your 
approval of a correction it intends 
to make to one of your functions. It 
is initially NIL. 


LAMBDASPLST DWIM uses the value of LAMBDASPLST to 
correct bad function definitions or 
LAMBDA expressions. Initially, it has 
the value (LAMBDA NLAMBDA). You may 
want to add to LAMBDASPLST if you 
define new function types via 
DWIMUSERFORMS. 


22.7.1 User-Directed Corrections and Transformations 


DWIMUSERFORMS allows you to specify your own corrections and transfor- 
mations before spelling correction is invoked. DWIMUSERFORMS is a list of 








* 
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forms that are evaluated in the order in which they appear. If any expression 
returns a non-NIL value, this value is treated as an expression to be evaluated. It 
is evaluated and the resulting value is returned as the value of FAULTEVAL or 
FAULTAPPLY. If all expressions on DWIMUSERFORMS return NIL, DWIM 
proceeds normally to attempt spelling correction. 

In order for an expression on DWIMUSERFORMS to attempt correction of 
an expression, it needs to have information about the context of the error. The 
following DWIM variables are made available to external functions (via SPEC- 
VARS) so that your functions may inspect them. 


FAULTX 


FAULTARGS 


FAULTAPPLYFLG 


TAIL 


Its value is an S-expression for 
errors concerning unbound atoms or 
CAR of expressions. Its value is the 
name of the function for undefined 
functions in APPLY. 


When an error occurs, DWIM places the 
cause of the error in FAULTX for you 
to inspect. 


Its value is the list of arguments 
appearing in an S-expression when an 
error of undefined function in APPLY 
occurs. To correct errors in the 
argument list, you may modify or 
reset FAULTARGS. 


If an undefined function in APPLY 
occurs, this flag is set to T to 
distinguish it from the case of an 
unbound atom (since FAULTX is atomic 
in both cases). 


After an expression has been 
evaluated on DWIMUSERFORMS and has 
returned a non-NIL value, this flag 
determines what to do with the 
result. If the flag is T, the 
resulting expression is a function to 
be applied, whereas, if it is NIL, it 
is an expression to be evaluated. 


If the error is an unbound atom, TAIL 
contains the CAR of the TAIL of the 
expression in which the unbound atom 
occurred. You can replace or correct 
the erroneous atom by executing 
(RPLACA TAIL <expression) ) 
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PARENT If the error is an unbound atom, 
PARENT is the expression in which the 
unbound atom appears. Thus, TAIL is 
set to (TAIL parent). 


TYPE-IN? This flag is true if the error 
occurred while you were typing at the 
keyboard. 

' FAULTFN This variable contains the name of 


the function in which the error 
occurred. Its value is TYPE-IN when 
the error occurs at type-in. Its 
value is EVAL or APPLY when those 
functions are explicitly invoked in 
your program. 


DWIMIFYFLG This flag is T if an error was 
encountered during an attempt to 
dwimify an expression as opposed to 
running a program. 


EXPR This variable contains the definition 
of the value of FAULTFN or the 
expression given to EVAL when an 
error occurred. 


22.7.2 The Spelling Lists 


A spelling list is merely a list of atoms. Many subsystems define their own spell- 
ing lists. DWIM maintains four spelling lists for spelling correction during nor- 
mal system operation: 


USERWORDS 

USERWORDS is a list of all words that are defined by the user via SET, SETQ, 
DEFINEQ, LOAD, and the various editing functions. It is used for spelling cor- 
rection by a number of different system function including BREAK, EDITF, 
ADVISE, and PRETTYPRINT. It is initially NIL. LASTWORD always con- 
tains the last word that was added to USERWORDS. Thus, if you have just 
defined a function via type-in and see an error, you may immediately edit it by 
simply typing (EDITF) or prettyprint it by typing (PP). 


SPELLINGS1 

SPELLINGS 1 is a list of function names used for spelling correction when an 
input is typed in “apply” format (i.e., using the square bracket protocol) and the 
function is determined to be undefined. It initially contains the most commonly 
used system functions. Whenever LISPX (see Section 25.2) is given an input in 
“apply” format, the name of the function is added to SPELLINGS1. 
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The initial value of SPELLINGS1 is: 


('[spellseparator]' DV MAKEFILE DF LOAD FILES? 
LOGOUT MOVD ENDLOADUP LOADUP) 


SPELLINGS2 

SPELLINGS2 is a list of function names for all other undefined functions, e.g., 
those that are usually used in ‘“‘eval”’ format. Whenever LISPX is given a non- 
atomic S-expression, the name of the function in the expression is added to 
SPELLINGS2. Function names for your functions are also added to SPELL- 
INGS2 by DEFINEQ, LOAD (when loading compiled code), UNSAVEDEF, 
EDITF, and PRETTYPRINT. 

The initial value of SPELLINGS2 is: 


«-SPELLINGS2 

('[spellseparator]' CALLS XPRESS SETBACKSPACE 
INITBACKSPACE INITFONTS DISPLAYTERMTYPE DISPLAYTERMP 
GETECHOMODE GETCONTROL GETRAISE GETDELETECONTROL 
HVREADEND HVREADER HPRINTO HREAD HVFWDREAD HVRPTREAD 
HVBAKREAD HVFWDCDREAD HPINITRDTBL READVARS 
MAKEHVPRETTYCOMS HPRINT1 HPRINT HPRINTBLOCK 
HPRINTBLOCKAO009 HPRINTBLOCKAO008 HCOPYALL1 HCOPYALLA0013 
HCOPYALL EQUALALL EQUALALLA0005 EQUALALLA0004 COPYALL 
COPYALLA0010 BRKDWNCLEAR RESULTS BRKDWNFBOXES BRKDWNINIT 
BRKDWNRESULTS BREAKDOWN BRKDWNBOXES BRKDWNTIME 
ASSEMBLETRAN READASCIZ SYSOUTP HELPBINSEARCH DODIRECTORY 
UNDELFILE /DELFILE /UNDELFILE DODIR DIRECTORY EQMEMBHASH 
STORETABLE MSLISTSET UPDATEFN UPDATECHANGED1 
UPDATECHANGED UNSAVEFNS) 


SPELLINGS3 
SPELLINGSS3 is a list of words used for correcting the spelling of unbound at- 
oms. Whenever LISPX is given an atom to evaluate, the name of the atom is 
added to SPELLINGS3. Atoms may also be added to SPELLINGSS3 if they are 
edited via EDITV or set via RPAQ/RPAQQ. 

When a file is loaded, all variables initialized as the result of File Package 
commands will also be added to SPELLINGS3. 

Atoms are also added to SPELLINGS3 when they are defined by SET or 
SETQ (as well as to USERWORDS). 

The initial value of SPELLINGSS is: 


<SPELLINGS3 

('[spellseparator]' MSANALYZECOMS SPELLINGS3 SPELLINGS2 
INITIALS AFTERSYSOUTFORMS LISPXCOMS X9FontsFamily 
FONTDEFS INITCOMS HOSTNAME SYSTEMTYPE CPUTIMEO 
CONSOLETIMEO CONSOLETIME CPUTIME EDITTIME GAINSPACEFORMS 
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HPRINT.SCRATCH ORIGECHOCONTROL ORIGTERMSYNTAX 
ORIGDELETECONTROL DONTCOPYDATATYPES HPRPTSTRING 
HPRINTRDTBL HPRINTHASHARRAY HPRINTMACROS HPRINTCOMS 
BRKDWNLST BRKDWNLABELS BRKDWNTYPE BRKDWNFLTFMT 
BRKDWNTYPES BRKDWNARGS BRKDWNCOMPFLG BRKDWNLENGTH 
BRKDWNCOMS NOSWAPFNS JSYSES FILEINFOTYPES DIRCOMMANDS 
DIRCOMS UTILITYCOMS HISTORYCOMS MASTERSCOPEDATE 
MSNEEDUNSAVE CHECKUNSAVEFLG RECORDCHANGEFN MSBLIP 
MSPATHSCOMS MCHECKBLOCKSCOMS DATABASECOMS NODUMPRELATIONS 
MSDATABASEINIT MSDBEMPTY MSDBCOMS MSHELPFILE MSAUXCOMS 
MSPRINTCNT MSPRINTFLG MSOPENFILES MSFILELST) 


Spelling List Sections 

Each spelling list is divided into two sections separated by a special marker, 
{spellseparator), which are known as the permanent and temporary sections. 
When a new word is first encountered, it is added to the front of the temporary 
section of the appropriate list. If the word already exists in the temporary sec- 
tion, it is merely moved to the front of that section. If the word is found in the 
permanent section, no action is taken. 

The lengths of the temporary sections for the lists SPELLINGx (x = 1,2,3) 
are determined by the variables #SPELLINGSx (x = 1,2,3). They are initialized 
to 30. #USERWORDS determines the length of the temporary section of 
USERWORDS. It is initialized to 60. You may redefine the values of these vari- 
ables via SETQ. A large value for #USERWORDS ensures that important words 
will be recorded, but at the expense of lengthier search times. 

When the length of a temporary section exceeds one of the variables de- 
scribed above, the last (e.g., oldest) word is forgotten by deleting it from the 
temporary section. This mechanism prevents the spelling lists from becoming 
cluttered with words that may have been used only once as an intermediate vari- 
able. 

When a word is corrected by the spelling corrector, that word is moved to the 
front of the corresponding spelling list. Thus, it is moved into the permanent 
section. Words that have been misspelled, and subsequently corrected, are con- 
sidered important and will not be forgotten. 


22.8 SPELLING FUNCTIONS 


Many of the spelling functions are available to you independently of their use by 
DWIM. You may want to use them when writing your own expressions to be 
placed in DWIMUSERFORMS or elsewhere in your program. 


22.8.1 Adding a Word to a Spelling List 
ADDSPELL adds a word to one of the four spelling lists. It takes the form 
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Function: ADDSPELL 
# Arguments: 3 


Arguments: 1) a word, WORD 
2) a spelling list index or the list 
itself, SPLST 
3) an index, INDEX 


Value: The new word added to the list. 
SPLST is interpreted as follows: 


1. If SPLST is NIL, then WORD is added to both USERWORDS and to 
SPELLINGS2. This value is used by DEFINEQ. 

2. If SPLST is 0, then WORD is added to USERWORDS. This value is 
used by LOAD (see Section 17.9.1) when loading EXPRs to property 
lists. 

3. If SPLST is 1, then WORD is added to SPELLINGS1. This value is used 
by LISPX (see Section 25.2). 

4. If SPLST is 2, then WORD is added to SPELLINS2. This value is used 
by LISPX (see Section 25.2). 

5. If SPLST is 3, then WORD is added to USERWORDS and SPELL- 
INGS3. 

6. If SPLST is a spelling list (ie., a list resulting from the evaluation of an 
argument to ADDSPELL), then INDEX is interpreted as the length of 
the temporary section. WORD is added to the end of the temporary sec- 
tion. 


ADDSPELL sets LASTWORD to the value of WORD when SPLST is NIL, 
0 or 3. 

If WORD is not a literal atom, ADDSPELL does nothing. If WORD is al- 
ready a member of a spelling list in its temporary section, WORD is moved to 
the front of that section. 

You may disable ADDSPELL by setting ADDSPELLFLG to NIL. 


A Definition for ADDSPELL 
We might define ADDSPELL as follows: 


(DEFINEQ 
(addspell (word splst index) 
(AND 
(LITATOM word) 
(SELECTQ splst 
((NIL 0) 
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(* 
DEFINE specifies NIL for SPLST which 
causes a word to be added to 
SPELLINGS2 because some user function 
must call it. However, the function 
may not be a top level function, so 
do not add it to SPELLINGS1 until it 
is used as such. 


(SETQ userwords 
(addspell1 word userwords 
#userwords) ) 
( AND 
(NULL splst) 
(SETQ spellings2 
(addspell1 word 


spellings2 
#spellings2) )) 
_ (SETQ lastword word) ) 
(1 
(* 
ADDSPELL is called from LISPX for 
APPLY mode inputs; the word is added 
to the permanent section. 
(SETQ spellings1 
(addspell1 word spellings1))) 
(2 
(* 
ADDSPELL is called from LISPX for 
EVAL mode inputs; the words are added 
to the permanent section. 
) 
(SETQ spellings2 
(addspell1 word spellings2) ) ) 
((T 3) 


(* 
ADDSPELL is called from LISPX for 
variables or by SAVESET, RPAQ, RPAQQ, 
SET, SETQ, or EDITV. 

) 

(SETQ userwords 

(addspelli word userwords 

#userwords) ) 

(SETQ spellings3 
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(addspell1 word 
spellings3 
#spellings3) ) 
(SETQ lastword word) ) 
(COND 
((LISTP splst) 
, (addspell1 word splst index) ) 
T 
(ERROR 'Bad addspell type' 
)) splst))))) 


DEFINE enters ADDSPELL with SPLST set to NIL. It adds words to 
SPELLINGS2 because a user function is being defined and some other user 
function will probably call it. But, it might not be a top level function (e.g., one 
invoked at typein), so it is not added to SPELLINGS1 until it is used in that 
fashion. 

Several functions, such as LOAD, use SPLST with a value of 0 so that the 
function is not added to SPELLINGS2 because there is no indication that the 
function will (ever) be called by the user. 

LISPX invokes ADDSPELL with SPLST set to 1 to handle ‘‘apply”’ format 
inputs. The input is added to the permanent section of SPELLINGS1 so that it is 
not forgotten. 

LISPX invokes ADDSPELL with SPLST set to 2 to handle “eval” format 
inputs. The input is added to the permanent section of SPELLINGS2 so that it is 
not forgotten. 

Several functions, such as SAVESET, RPAQ, SETQ, EDITV, and vari- 
ables given to LISPX, invoke ADDSPELL with SPLST set to 3. The variable 
names are added to the temporary section of SPELLINGS3. 


ADDSPELLI 
ADDSPELL1 is the workhorse function used by ADDSPELL. We might define 
ADDSPELLI as follows 


(DEFINEQ 
(addspell1 (word splst index) 
(COND 
((NULL splst) 
(* 
The spelling list is empty, so create an 
entry for it. 


) 
(SETQ splst (LIST NIL word) )) 


( (AND 
(NEQ word (CAR splst) ) 
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(NEQ word (CADR splst))) 


(* 


The above expressions make a quick check 
of the first two words of the spelling 
list under the assumption that the 
spelling error might have occurred 
recently. 


(PROG (alist1 alist2 alist3 tmplen) 


loop 


(* 
ALIST1 and ALIST2 are sublists of 
SPLST that track a search through it 
so elements may be added or deleted. 
TMPLEN is the length of the temporary 
section. 


) 
(SETQ alisti splst) 
(SETQ alist2 (CDDR splst)) 
(COND 
( (NULL (CAR splst) ) 
(SETQ alist3 splst) 
(SETQ tmplen 1)) 
((NULL (cADR splst) ) 
(SETQ alist3 splst) 
(SETQ tmplen 0))) 


(COND 
((NULL alist2) 
(* 
This check occurs because 
USERWORDS has NIL as its 
first entry, i.e., there 
are no permanent user 
words. If NIL is not 
noticed, the length will 
not be determined and 
nothing will ever be 
deleted. 


(GO exit.addspel11) ) 
((EQUAL word (CAR alist2)) 
(COND 
( (NULL alist3) 
(* 


The word is 
already in the 
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permanent 
section. 
) 
NIL) 
((NULL index) 
(* 
The word is in 
the temporary 
section. Add it 
to the permanent 
section and erase 
it from the 
temporary 
section. 
) 
(RPLACD (CDR alisti1) 
(CDR alist2) ) 
(RPLACD alist2 
(CDR alist3)) 
(RPLACD alist3 
alist2)) 
(T , 
(* 
The word is in 
the temporary 
section. Move it 
to the front of 
the temporary 
section. 


(RPLACD (CDR alisti) 
(CDR alist2)) 
(SETQ alist3 
(CDR alist3)) 
(RPLACD alist2 
(CDR 
alist3) ) 
(RPLACD alist3 
alist2) )) 
(RETURN) ) 
((NULL (car alist2)) 
(* 


The CAR of alist3 is the 
last member of the 
permanent section. 
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(SETQ alist3 (CDR alisti)) 
(SETQ tmplen 0))) 
(SETQ alist1 (CDR alist1)) 
(SETQ alist2 (CDR alist2)) 
(AND tmplen 
(addivar tmplen) ) 
(GO loop) 
exit.addspell1 
(COND 
((NULL alist3) 
(* 
NIL not found in the 
spelling list. This occurs 
if the user is maintaining 
his own spelling list and 
not using the temporary and 
permanent conventions. 
'! 
(NCONC1 alist1 word)) 
((NULL index) 
a 


Add the word at the end of 
the permanent section. 


(RPLNODE alist3 
(CAR alist3) 
(CONS word 
(CDR alist3)))) 
((IGREATERP m index) 
(* 


Add the word at the 
beginning of the temporary 
section. Delete and reuse 
the last element of the 
temporary section. 


) 
(RPLNODE (CDR alist1) 
word 
(CDDR alist3) ) 
(RPLNODE (CDR alist3) 
(CADR alist3) 
(CDR alist1) ) 
(RPLACD alist1 NIL) ) 


(* 


(T 
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Add the word at the 
beginning of the temporary 
section. 
) 
(RPLNODE (CDR alist3) 
(CADR alist3) 
(CONS word 
(CDDR 


alist3)))))))) 
splst) ) 


Using ADDSPELL 

Many of your programs will create entries on lists as a result of a user entering 
data to an application. These entries may not be added to a system spelling list 
because they are not defined by SETQ or DEFINEQ. In these cases, you may 
wish to invoke spelling correction on a spelling list that is associated with the 
application. You can do so by creating an atom that will have as its value the 
spelling list. Then you may add a word to the spelling list by invoking ADD- 
SPELL directly. 


«(SETQ my.spelling.list 
(initialize.spelling.list 'my.spelling.list) ) 
('[spellseparator]' MY.SPELLING.LIST) 


«-(ADDSPELL ‘uganda my.spelling.list 3) 
('[spellseparator]' MY.SPELLING.LIST UGANDA) 


where we have made the name of out spelling list an entry in itself to ensure that 
it is spelling corrected as well. Consider several more additions: 


<-(ADDSPELL 'kenya my.spelling.list 3) 
('[spellseparator]' MY.SPELLING.LIST UGANDA KENYA) 


«(ADDSPELL 'egypt my.spelling.list 3) 
('[spellseparator]' MY.SPELLING.LIST UGANDA KENYA EGYPT) 


«-(ADDSPELL 'sudan my.spelling.list 3) 
('[spellseparator]' MY.SPELLING.LIST KENYA EGYPT SUDAN) 


where the oldest name on the spelling list has been forgotten because we speci- 
fied a length of three words. Now, if we add a new word without the length speci- 


fication: 


<-(ADDSPELL 'libya my.spelling.list) 
('[spellseparator] ' LIBYA MY.SPELLING.LIST KENYA EGYPT 


SUDAN) 
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A Definition for INITIALIZE.SPELLING.LIST 
We might define INITIALIZE.SPELLING.LIST as follows: 


(DEFINEQ 
(initialize.spelling.list (x) 
(LIST (CAR USERWORDS) 
x) 


)) 


where we need to capture the spelling separator. 


22.8.2 Finding a Misspelling 
MISSPELLED? determines if a word is misspelled. It takes the form 


Function: MISSPELLED? 
# Arguments: 6 


Arguments: 1) a mispelled word, XWORD 
2) a relative agreement, REL 
3) a spelling list, SPLST 
4) a flag, FLAG 
5) an expression for correction, TAIL 
6) a function, FN 


Value: See below. 
MISSPELLED? operates as follows: 


1. If XWORD is NIL or (ESC), MISSPELLED? prints = followed by the 
value of LASTWORD. It returns LASTWORD as the respelling without 
asking for approval. 

2. MISSPELLED? determines if XWORD is really misspelled. If FN ap- 
plied to XWORD returns T or XWORD appears on SPLST, then MIS- 
SPELLED? returns XWORD. 


3. Otherwise, MISSPELLED? attempts to fix the spelling of XWORD via 


(FIXSPELL xword rel splst flg tail fn tieflg 
dontmovetopflg) 


A Definition for MISPELLED? 
MISPELLED? might be defined as: 


(DEFINEQ 
(mispelled? (xword rel splst flag tail fn) 
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(AND DWIMFLG 
(NULL NOSPELLFLG) 
(PROG NIL 
(RETURN 
(COND 
((OR (NULL xword) 

(EQ xword <ESC))) 
(* 


If you press the 
ESCAPE key, LISPX 
interprets this as 
meaning the last thing 


typed. 
) 
(PRIN1 '= T) 
(PRINT LASTWORD T T)) 
( (COND 
((NULL fn) 
(* 
If no selection 
function, 
determine if 
XWORD exists in 
the spelling 
list. 
(MEMBER xword splst) ) 
(T 
(APPLY* fn xword) )) 
xword) 
(T 
(FIXSPELL xword 
rel 
splst 
flag 
tail 


fn)))))))) 


22.8.3 Fixing the Spelling of a Word 
FIXSPELL is the spelling corrector. It takes the form 


Function: FIXSPELL 
# Arguments: 8 
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Arguments: 1) a word to be corrected, XWORD 
2) a relative agreement, REL 
3) a spelling list, SPLST 
4) a flag, FLG 
5) an expression tail, TAIL 
6) a function, FN 
7) a tie flag, TIEFLAG 
8) a movement indicator, DONTMOVETOPFLG 


Value: The respelling of XWORD or NIL. 


If XWORD is NIL or (ESC), the respelling is the value of LASTWORD. 
This is returned without asking your approval. This allows you to immediately 
apply functions such as EDITF and PP that expect a single literal atom as an 
argument. 

If XWORD contains lower case characters, and the corresponding upper 
case word is correct, the upper case word is returned as its value. The upper case 
word must be on SPLST or satisfy FN (i.e., it returns T). 

REL is a measure of relative agreement used to determine the closeness of 
two words. If it is NIL, then FIXSPELLREL is used as the default. When you 
call FIXSPELL directly, you may want to experiment with different values of 
REL depending on the lengths of words that you will using. 

If FLG is NIL, the spelling correction is performed as if you had typed in the 
word (whether or not you actually did!). In this case, XWORD will not be typed, 
and your approval! will not be sought. 

If FLG is T, then XWORD is typed, followed by =, and your approval is 
requested if APPROVEFLG is T. 

If FLG is NO-MESSAGE, the correction is returned with no further pro- 
cessing. It has the same effect as executing CHOOZ. The correction is a pair of 
words. 

If TAIL is non-NIL, and the correction is successful, FIXSPELL makes the 
correction using /RPLACA (so that is undoable). It also corrects misspellings do 
to running two words together without an intervening space. In this case, it re- 
places the CAR of TAIL, where the runon occurred, with two words which con- 
tain the intervening space. 

If TIEFLAG is NIL, and a “tie” occurs, FIXSPELL returns NIL. A “‘tie” 
occurs when two or more words on the spelling list have the same degree of 
agreement with XWORD. No correction occurs because FIXSPELL cannot 
wdecide which is the better choice. 

You may influence the choice by setting TIEFLAG as follows: 


1. If TIEFLAG is PICKONE, the first word found will be used as the spell- 
ing correction for XWORD. 

2. If TIEFLAG is LIST, FIXSPELL returns a list of the possible corrections 
for XWORD (i.e., all of the possible candidates). Your program must 
decide which it likes best and make the appropriate correction. 
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3. If TIEFLAG is EVERYTHING, a list of all candidates whose degree is 
above REL will be returned. This includes that tie in degree as well as 
those which may be better. 


If DONTMOVETOPELG is T, and a spelling correction is made, the cor- 
rected word will not be moved to the beginning of the spelling list. In this way, 
you may prevent the propagation of large numbers of words to the permanent 


section of the spelling list which the system would consider important, but you 
surely don’t. 


Using FIXSPELL 
First, let us set up a private spelling list. 


<-(SETQ mywords (LIST (CAR USERWORDS)) ) 
('{spellseparator] ') 


which sets up your own spelling list with the separator in place. (Note: what is 
needed is a function to create a spelling list). 
Now, let us add a few words to the spelling list MYWORDS. 


«(SETQ #MYWORDS 10) 
10 


«-(ADDSPELL 'YANKEES MYWORDS #MYWORDS) 
('[spellseparator]' YANKEES) 


<-(ADDSPELL 'PIRATES MYWORDS #MYWORDS) 
(YANKEES '[spellseparator]' PIRATES) 
Now, let us try to correct a word: 


«-(FIXSPELL 'YANKES 70 MYWORDS) 
=YANKEES 
YANKEES 


«-(FIXSPELL 'PRTES 50 MYWORDS) 
=PIRATES 
PIRATES 


But, if we increase the relative agreement to 75, we do not obtain a correc- 
tion: 


«-(FIXSPELL 'PRTES 75 MYWORDS) 
NIL 
Now, let use the same word with FLAG set to T: 
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«-(FIXSPELL 'PRTES 50 MYWORDS T) 
PRTES = PIRATES? ...yes 
PIRATES 


where we allowed the default time to expire and correction to proceed. 
Now, let us add two word forms to the spelling list that have close spellings 
to each other. 


«-(ADDSPELL 'NEW-YORK-METS MYWORDS #MYWORDS) 
(YANKEES PIRATES '[spellseparator]' NEW-YORK-METS) 


«-(ADDSPELL 'NEW-YORK-JETS MYWORDS #MYWORDS) 
(YANKEES PIRATES '[spellseparator]' NEW-YORK-JETS 
NEW-YORK-METS) 


Now, let us attempt to correct the spelling of a word: 


«-(FIXSPELL 'NEW-YORK-ETS 75 MYWORDS) 
NIL 


because more than one word matches the word to be corrected and TIEFLAG is 
NIL. Now, let us set TIEFLAG to LIST and try again: 


<(SETQ TIEFLAG 'LIST) 

LIST 

«+-(FIXSPELL 'NEW-YORK-ETS 75 MYWORDS NIL NIL NIL TIEFLAG) 
(NEW-YORK-JETS NEW-YORK-METS) 

Now, let us set TIEFLAG to PICKONE and try again: 

«-(SETQ TIEFLAG 'PICKONE) 

PICKONE 


«-(FIXSPELL 'NEW-YORK-ETS 75 MYWORDS NIL NIL NIL TIEFLAG) 
=NEW-YORK-METS 
NEW-YORK-METS 


22.8.4 Checking a Function Name Spelling 


FNCHECK determines whether or not a word is a function name, and if it is, 
whether or not its spelling is correct. It takes the form 


Function: FNCHECK 
#Arguments: 5 
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Arguments: 1) a function name, FN 
2) an error flag, NOERRORFLAG 
3) a spelling flag, SPELLFLAG 
4) a property flag, PROPFLAG 
5) a tail expression, TAIL 


Value: The corrected name. 


FNCHECK is called by many functions to determine if FN is a function (ex- 
amples are ARGLIST, GETD, SAVEDEF). If FN is a function, then EN is re- 
turned as the value of FNCHECK. If FN is not a function, FNCHECK attempts 
spelling correction if DWIMFLG has the value T. The IRM notes that this al- 
lows FNCHECK to operate in small INTERLISP systems where DWIM is not 
present. 

(Note: at the present time, every INTERLISP system has a standard loadup 
that includes DWIM. Future versions may allow the user to configure his own 
INTERLISP system. By the time this book is published, Xerox may have an- 
nounced this feature.) 

NOERRORFLAG determines whether or not FNCHECK handles the un- 
successful case. If NOERRORFLG is T, FNCHECK simply returns NIL. 


<— (FNCHECK 'MISPELLD? ) 
MISPELLD? not a function 


«-(FNCHECK 'MISPELLD? T) 
NIL 


Otherwise, FNCHECK prints a message and generates a non-breaking er- 
ror. 

SPELLFLAG corresponds to MISSPELLED?’s fourth argument in that it 
determines whether approval is sought for the spelling correction. MIS- 
SPELLED? is called by FNCHECK to correct the spelling of FN. 

PROPFLAG is used when FN does not have a function definition, but does 
have an EXPR property. If PROPFLAG has the value T, FN is considered to be 
the name of a function and FN will be returned. Otherwise, if PROPFLAG is 
NIL, FN is not considered to be the name of a function, and NIL is returned or 
an error generated depending on the value of NOERRORFLAG. 


22.8.5 Correcting File Name Spelling 
SPELLFILE is used to correct the spelling of a file name. It takes the form 


Function: SPELLFILE 
# Arguments: 4 
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Arguments: 1) a file name, FILE 
2) a print flag, NOPRINTFLAG 
3) a spelling flag, NOSPELLFLAG 
4) a directory list, DIRLST 


Value: The corrected file name; otherwise, NIL. 


SPELLFILE attempts to correct the spelling of a file name by searching one 
or more directories for a file name corresponding to FILE. 

If FILE has a directory field, SPELLFILE examines the specified directory. 
Otherwise, it uses the directories specified in DIRLST. If DIRLST is NIL, 
SPELLFILE uses the value of DIRECTORIES which is initially (NIL LISP). 
NIL indicates that the user’s login directory is to be used as the default. 

If NOPRINTFLAG is T, SPELLFILE does not print any correction nor does 
it ask for your approval of the correction. 

If NOSPELLFLAG is T, no spelling correction will be attempted, although 
searching through DIRECTORIES will be performed. 

SPELLFILE is used on ERRORTYPELST to handle FILE NOT FOUND 
errors. The initial entry is: 


((23 (SPELLFILE (CADR ERRORMESS) NIL NOFILESPELLFLG) ) ) 


The value of NOFILESPELLFLG is initially T. But, setting it to NIL will 
allow SPELLFILE to correct the spelling of the file name whenever an error oc- 
curs. 


Finding a File 

An alternative form, FINDFILE, attempts to locate a file in one or more directo- 
ries. If the file name is misspelled, it calls SPELLFILE to correct the spelling, 
but with no printing interaction. It takes the form 


Function: FINDFILE 


# Arguments: 3 


Arguments: 1) a file name, FILE 
2) a spelling flag, NOSPELLFLAG 
3) a directory list, DIRLST 


Value: The file name. 
We might define FINDFILE as follows: 


(DEFINEQ 
(findfile (file nospellflag dirlst) 
(COND 
((INFILEP file) file) 
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(T 
(SPELLFILE file T nospellflag 
dirlst) ) ) 
)) 


22.8.6 A Spelling Correction Example 


In this section, we try to show how all of these functions work together to correct 
a word. We do so by tracing the major functions that we have discussed. We use 
the small spelling list that was created in our discussion of ADDSPELL above. 


«(TRACE MISSPELLED?) 
(MISSPELLED?) 


«(TRACE FIXSPELL) 
(FIXSPELL) 


«(TRACE CHOOZ) 
( CHOOZ ) 


(TRACE SKOR) 
(SKOR) 


«-(MISSPELLED? 'SUDNA NIL MY.SPELLING.LIST) 


where SUDAN is incorrectly spelled as SUDNA. With DWIM enabled in trust- 
ing mode, the following trace appears: 


MISSPELLED? : 
XWORD=SUDNA 
REL=NIL 
SPLST=(SUDAN '[spellseparator]' LIBYA MY.SPELLING.LIST 
EGYPT KENYA) 
FLG=NIL 
TAIL=NIL 
FN=NIL 
FIXSPELL: 
XWORD=SUDNA 
REL=NIL 
SPLST=(SUDAN '[spellseparator]' LIBYA 
MY.SPELLING.LIST EGYPT KENYA) 
FLG=NIL 
TAIL=NIL 
FN=NIL 
TIEFLG=NIL 
DONTMOVETOFLG=NIL 
FROMDWIM=NIL 
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APPROVALFLG=NIL 
CHOOZ: 
XWORD=(83 85 68 78 65) 
REL=70 
SPLST=(SUDAN '[spellseparator]' LIBYA 
MY.SPELLING.LIST EGYPT KENYA) 
TAIL=NIL 
FN=NIL 
TIEFLG=NIL 
NDBLS=0 
FROMDWIM=NIL 
SKOR: 
XWORD=(83 85 68 78 65) 
TWORD=(83 85 68 65 78) 
NCX=5 
NCT=5 
FROMDWIM=NIL 
SKOR=0 
CHOOZ=SUDAN 
=SUDAN 
FIXSPELL=SUDAN 
MISSPELLED? =SUDAN 
SUDAN 


Note that the list of numbers received by CHOOZ is the list of character 
codes that make up the word to be checked. SKOR receives the character codes 
for both the word to be checked and the candidate word. 

The value of REL has a significant effect on whether or not spelling correc- 
tion is successful. Consider the example (where I will leave out most of the trac- 
ing information): 


«-(MISSPELLED? 'KNYA 90 MY.SPELLIN.LIST) 
MISSPELLED? : 

XWORD=KNYA 

REL=90 


FIXSPELL: 
XWORD=KNYA 
REL=90 
CHOOZ: 
XWORD=(75 78 89 65) 
REL=90 


CHOOZ=NIL 
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FIXSPELL=NIL 
MISSPELLED? =NIL 
NIL 


However, if we specify a relative agreement of 50, we obtain the following 
result (where much of the tracing information is omitted): 


<-(MISSPELLED? 'KNYA 50 MY.SPELLING.LIST) 
MISSPELLED? : 

XWORD=KNYA 

REL=50 


FIXSPELL: 
XWORD=KNYA 
REL=50 
CHOOZ: 
XWORD=(75 78 89 65) 
REL=50 
SKOR: 
XWORD=(75 78 89 65) 
TWORD=(69 71 89 80 84) 
NCX=4 
NCT=5 


SKOR: 
XWORD=(75 78 89 65) 
TWORD=(83 85 68 65 78) 
NCX=4 
NCX=5 


{other attempts) 

SKOR: 
XWORD=(75 78 89 65) 
TWORD=(75 69 78 89 65) 
NCX=4 
NCT=5 


SKOR=1 
CHOOZ=KENYA 
=KENYA 
FIXSPELL=KENYA 
MISSPELLED? =KENYA 
KENYA 
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Timing Results for Spelling Correction 

Using BREAKDOWN (see Section 29.3), we can obtain some timing estimates 
for how long it takes to do simple spelling correction. We will use the same spell- 
ing list that we used in the previous example: 


«(BREAKDOWN 'MISSPELLED? 'FIXSPELL 'CHOOZ 'SKOR) 
(MISSPELLED? FIXSPELL CHOOZ SKOR) 


«-(MISSPELLED? 'UGANDI 50 MY.SPELLING. LIST) 


=UGANDA 

UGANDA 

< (BRKDOWNRESULTS) 

FUNCTIONS TIME #CALLS PER CALL % 
MISSPELLED? .012 1 .012 10 
FIXSPELL .018 1 .018 16 
CHOOZ .047 1 .047 Al 
SKOR .039 5 .008 34 
TOTAL .116 8 .015 


NIL 








23 





Conversational LISP 


INTERLISP is unlike any other “traditional” programming language. A num- 
ber of factors make this so! First, it has a very simple syntax—everything is a list 
or an atom. If it is a list, then the first element of the list may somehow be inter- 
preted as the name of a function if that list is given to EVAL. What is data at one 
moment is a function call the next. The structure of a list is enforced through a 
myriad of parentheses. 

Second, INTERLISP has no reserved words. Also, it has function names 
which have a historical basis that, in many cases, are but a memory. Sometimes, 
you must think about what a function does because, although a function sounds 
“right,”’ it is not necessarily right for every instance. This becomes more confus- 
ing when you have multiple function names that all sound like they do the same 
thing but have subtle differences. 

INTERLISP programs, even single functions, are difficult to read. Read- 
ability in traditional languages is enhanced by syntactic cues such as certain 
types of statements beginning on a new line or specific punctuation to terminate 
a statement. INTERLISP has none of these features. When you encounter mul- 
tiple parentheses, particularly in a nested function definition, it is very hard to 
keep track of which right parenthesis goes with which left parenthesis. 

INTERLISP uses parentheses for almost all syntactic forms for its own ben- 
efit rather than the user’s (reader’s). Thus, there is very little syntactic informa- 
tion carried in the parenthesis notation. Experienced INTERLISP programmers 
tend to ignore the parentheses and focus on the keywords within the lists that 
make up INTERLISP functions. After some practice, your eye will become 
trained to picking out the meaning of a function from its structure (i.e., the form 
of coding) as opposed to “reading” the function. 

However, good programming practice emphasizes that programs should be 
readable by others as well as oneself. To enhance the readability of INTERLISP 
programs, Teitleman [teit73] developed Conversational LISP (CLISP) to make 
INTERLISP programs easier to read and write. CLISP borrows many program- 
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ming constructs from traditional languages. Usually, users are more familiar 
with these constructs than with basic INTERLISP formalisms. 

CLISP augments INTERLISP syntax rather than replacing it. You may in- 
termix INTERLISP and CLISP syntax freely in a function without having to 
identify what mode (since INTERLISP is modeless) you are in. 


23.1 HOW CLISP OPERATES 


CLISP is an integral part of INTERLISP. Thus, you may begin programming in 
CLISP without any further preparation (other than reading Sections 23.2 
through 23.5). 

CLISP sits between you and the INTERLISP interpreter. When you type a 
CLISP statement at the top level, an ‘‘error’’ occurs because the interpreter does 
not recognize the CLISP syntax. DWIM (see Chapter 22) is called to determine 
how to process the “error.” It transforms the CLISP statement into an equiva- 
lent INTERLISP expression and passes it to the interpeter for evaluation. Un- 
like other errors, you will not be asked to approve the translation and no error 
message will be generated. Thus, CLISP translation occurs transparently to the 
user. 

CLISP statements are handled by DWIM. When a CLISP statement is en- 
countered, it is unrecognized by the intepreter which calls DWIM to do some 
sort of correction. DWIM processes the statement, collecting error messages as 
it goes. Either DWIM successfully translates the statement, whence it is exe- 
cuted directly, or DWIM displays error messages at your terminal. 

However, if DWIM encounters a syntactic error in your CLISP statement, it 
does not complete the translation. Rather, it prints a diagnostic that identifies 
the error and waits for you to correct it. When DWIM encounters a valid CLISP 
statement, but one in which an operand is unbound, DWIM asks you whether or 
not to treat it as CLISP. 

Because CLISP statements are intercepted by DWIM and translated to the 
corresponding INTERLISP forms, you pay a penalty in slower execution due to 
interpretation of the CLISP expression. You should keep this in mind when tim- 
ing functions containing CLISP statements. However, this penalty disappears 
when you compile your functions because all CLISP statements are translated to 
INTERLISP expressions before compilation. 


23.1.1 Translating CLISP Expressions 


CLISP expressions are handled by replacing the expression with the correspond- 
ing INTERLISP expression. The original CLISP expression will be discarded 
(actually, it is retained in the hash array CLISPARRAY as a translation). How- 
ever, the translation will replace the CLISP expression in the function definition 
unless CLISPRETRANFLG is T. 

CLISP statements are discarded because they may easily be recomputed us- 
ing CLISPIFY. They are also discarded because even though the CLISP state- 
ment contained errors, these will be corrected during translation by DWIM. 
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23.2 CLISP OPERATORS 


CLISP recognizes a wide variety of operators that enable you to program more 
efficiently. These operators may be divided into the list, infix, and prefix classes. 


23.2.1 List Operators 


CLISP uses angle brackets—{ )—as a shorthand notation for specifying the list 
construction. The appearance of a ‘‘{”’ is interpreted as equivalent to “(’’. When 
CLISP encounters a left angle bracket, it begins the construction of a list. Every- 
thing up to the matching right angle bracket will be included in the list. 


< (SETQ old-time-players 


« 'musial 'wagner 'cobb 'triandos )) 
(musial wagner cobb triandos) 


would construct a list equivalent to executing 
(LIST 'musial 'wagner 'cobb 'triandos) 
Angle brackets may be nested to indicate sublists of lists as follows: 


< (SETQ more-players 
{ 'ruth 'maris <« 'aaron 'robinson ))) 
(ruth maris (aaron robinson) ) 


is equivalent to 
(LIST 'ruth 'maris (LIST 'aaron 'robinson) ) 


! Operator 

The exclamation point—!—operator indicates that the following element is to be 
included in the list as a segment, i.e., when CLISP encounters a !, it performs a 
CONS to construct a list. 


«-(SETQ double.play.team ¢ 'tinker 'evers ! ‘chance )) 
(tinker evers . chance) 


is equivalent to 


<(SETQ double.play.team 
(CONS 'tinker (CONS 'evers 'chance) )) 


whereas 


«(SETQ double.play.team ¢ ! 'tinker ! 'evers 'chance )) 
(chance) 
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is equivalent to 


+(SETQ double.play.team 
(APPEND 'tinker 'evers (LIST 'chance))) 


!! Operator 

The double exclamation point—!!—operator accomplishes two functions: it in- 
dicates that what follows is included in the list as a segment, and that anything in 
angle brackets to its right is physically attached to it. 


—(SETQ pitchers < !! 'koufax 'seivers 'ryan)) 
(seivers ryan) 


is equivalent to 


«-(SETQ pitchers (NCONC 'koufax 'seivers 'ryan)) 


and 


«-(SETQ pitchers < !! 'drysdale ! 'feller ! 'johnson )) 
feller 


is equivalent to 


«-(SETQ pitchers 
(NCONC 'drysdale (APPEND 'feller 'johnson) )) 


Note that the previous form did not translate to 
(NCONC (APPEND 'drysdale 'feller) 'johnson) 


which has the same value but the wrong structure. The latter would attach 
“iohnson”’ to “feller” but not attach either to “‘drysdale”’. 

These operators—{, !, !!, and )—have been described as separate. atoms, 
but they need not be. Moreover, our simple examples do not preclude the use of 
more complex statements within angle brackets such as complete CLISP state- 
ments. 

Note that CLISP attempts to match pairs of angle brackets properly. Thus, 
if a right angle bracket follows a quoted atom, the list structure will not be com- 
pleted. 


«+ < 'mays 'spahn 'campanella) 
undefined CAR of form 


because ) is treated as part of the atom CAMPANELLA. You must separate 
CLISP operators from other symbols in an input line by at least one space. 





23.2 CLISP Operators 837 


23.2.2 Infix Operators 


CLISP recognizes several standard arithmetic symbols as shorthand notation for 
the corresponding INTERLISP functions. The symbols and their corresponding 
functions are 


Symbol Function 


+ IPLUS, FPLUS 

IDIFFERENCE or IMINUS, FDIFFERENCE 
ITIMES, FTIMES 

IQUOTIENT, FQUOTIENT 

EXPT T 


>“ OK CO*d 


Operators have the normal precedence that one expects. As usual, normal 
precedence may be overridden by proper grouping of arithmetic expressions 
with parentheses. Consider the following examples: 


—12*12/6-4+100 
120 


+ (12*12) 
144 


—210 
1024 


-0/6 
0 


<(SETQ x 12) 
12 


<(SETQ y 100) 
100 


<(SETQ z 24) 
24 


—XXY/Z 

50 

<(SETQ A (CONS X Y)) 

(12 . 100) 

«((CAR A)*(CDR A)/Z) 

50 

<"THE LAZY BOY" + "THE BROWN DOG" 


NON-NUMERIC ARG 
"THE LAZY BOY" 





838 Conversational LISP 


The flexibility of the CLISP arithemtic infix operators allows you to perform 
simple arithmetic computations easily and directly at the top level. You may use 
literal atoms as the arguments for the CLISP infix operators. You may also use 
expressions that evaluate to numbers. Note that an extra pair of parentheses is 
required in the example above because LISPX (see Section 25.2) begins evalua- 
tion as soon as its detects a matching, balanced right parenthesis. The argu- 
ments are passed to the appropriate arithmetic functions which perform any er- 
ror detection. 


Relational Operators 
CLISP also recognizes a shorthand notation for relational operators which is 
modeled after the Fortran operators. These include 


Symbol Function 
= IEQP 
GT IGREATERP 
LT ILESSP 
GE IGREATERP/IEQP 
LE ILESSP/IEQP 


Within an S-expression, CLISP will recognize Boolean operators such as 
AND, OR, MEMBER, and EQUAL. Consider the following examples: 


-—X=Y 
NIL 


+X LE Y 
ns 


— X * Z GE Y/3 
¥ 


: Operator . 
: is an infix operator that specifies the extraction of the substructure of a list. 


«-(SETQ employees '(steve john sue kathy)) 
(steve john sue kathy) 

<employee:4 

kathy 


means to extract the fourth element of the list that is the value of ‘‘employee’”’. 


:: Operator , 
:: indicates that the extraction is to be taken with reference to the tail of the list. 
Thus, assuming a list of the president’s last names, we have 
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“presidents: :2 
(carter reagan) 


+ Operator 

+ is an infix operator that indicates assignment. This operator is used heavily by 
the Record Package (see Chapter 27). In its simplest form, x+y is translated as 
(SETQ x y). By combining + with : and ::, you may modify any portion of the 
structure of a list. Thus, x:2+-y is interpreted as (replace the second element of 
X with Y) and becomes (RPLACA (CDR x) y). 

The « operator has a different precedence on the left than on the right. On 
the left, « has a higher precedence than other operations except for ' and :. On 
the right, « has broader scope, so that a~b+c means a+-(b+c). 

Note: I have represented the “‘left arrow’’ or assignment operator as a com- 
position of the two symbols « and—because most terminals (mine included) do 
not possess such a symbol on the keyboard. 


<-players*-<musial ruth cobb wagner) 
(musial ruth cobb wagner) 


Warning!!! 

Many examples in this text were taken from a Xerox 1100 running IN- 
TERLISP-D whose prompt character is a ‘‘left arrow."’ Please be careful not to 
confuse the two uses of the left arrow. 


23.2.3 Prefix Operators 


CLISP recognizes several symbols as prefix operators. You are already familiar 
with one operator from the early chapters of this book. This is the ' operator 
which means to QUOTE its argument. It is now revealed that this is, in fact, a 
CLISP operator. Consider the CLISP expression 


x='y means (EQ x (QUOTE y)) 


Following ', all operators are ignored until the next separator. Thus the 
expression 


'y=y is translated as (QUOTE x=y). 


" Operator ; 
" is a prefix operator that indicates the logical negation of its argument. It is 


translated as (NOT argument). 


"(ASSOC 'disney presidents) 
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is translated as 
(NOT (ASSOC 'disney presidents) ). 


'' may also be used to negate an infix operator. Thus, the expression (x "GE 
y) is translated as (x LT y). 


23.2.4 Operator Precedence 


CLISP assigns a precedence to each of the operators it recognizes. When many 
operators and operands are strung together in an expression without the benefit 
of demarcating parentheses, precedence is required to tell CLISP how to prop- 
erly translate the expression. The precedences of all the operators are given in 
the following table (from highest to lowest): 


Operator Precedence Table 


<- (left precedence) 
",—(unary) 


*, / 

+,—(binary) 

«- (right precedence) 
INTERLISP forms 

LT, GT, EQUAL, MEMBER, etc. 
AND 

OR 

IF, THEN, ELSEIF, ELSE 
iterative statement operators 


For a discussion of precedence, consult any good textbook on language the- 
ory. ? 


23.2.5 CLISP Declarations 


CLISP provides default functions for all of its operators. Thus, the arithmetic 
operators use either integer or floating point functions as determined by the na- 
ture of their arguments. The relational operators use the integer functions as 
default. The CLISP declarations for each operator are maintained on the prop- 
erty list of the atom representing the operator. 

You may declare new interpretations for CLISP operators using CLISP- 
DEC, which takes the form 
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Function: CLISPDEC 

# Arguments: 1 

Arguments: 1) a declaration list, DECLST 
Value: The value of DECLST. 


CLISPDEC records the declarations in a global table. The declarations are 
processed in the order in which they appear in DECLST, so that later declara- 
tions will override earlier ones. The initial global declarations are INTEGER 
and STANDARD. Declaration atoms are taken from the following table. 


Declaration INTERLISP Functions Used 

INTEGER IPLUS, IMINUS, IDIFFERENCE, ITIMES, 

FIXED IQUOTIENT, ILESSP, IGREATERP 

FLOATING FPLUS, FMINUS, FIDFFERENCE, FTIMES, 
FQUOTIENT, FLESSP, FGREATERP 

MIXED PLUS, MINUS, DIFFERENCE, TIMES, 
QUOTIENT, LESSP, GREATERP 

FAST FRPLACA, FRPLACD, FMEMB, FLAST, 
FASSOC 

UNDOABLE /RPLACA, /RPLACD, /NCONC, /NCONC1, / 
MAPCONC, /MAPCON 

STANDARD RPLACA, RPLACD, MEMB, LAST, ASSOC, 


NCONC, NCONC1, MAPCONC, MAPCON 
Consider the following examples: 
-X *Y 
1200 


«-(CLISPDEC ' (FLOATING) ) 
(FLOATING) 


-X * Y 
1200.0 


Note that CLISP now uses the floating point functions rather than the inte- 
ger functions to compute the arithmetic result. 


Overriding Global Declarations 
CLISPDEC places its declarations in a global table. You may override the global 
declarations for individual functions by placing a local declaration expression 
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immediately after the argument list of a function. The local declaration expres- 
sion takes the form 


(CLISP: . <declarations) ) 


Consider the function ADD3 which adds the three numbers given as its ar- 
guments. ADD3 is defined using CLISP arithmetic operators as follows: 


<— (DEFINEQ 
(add3 (x y 2) 
X+Yt+2Z 
)) 


(ADD3 ) 


<(ADD3 12 20 34) 
66 


Now, we can override the normal arithmetic functions used to translate the 
CLISP form by placing a local declaration in the function definition (via AD- 
VISE or the Editor). ADD3 now appears as 


«(PP add3) 
(ADD3 
(LAMBDA (X Y Z) 
(CLISP: . (FLOATING)) 


Ye VazZ 
)) 
<(ADD3 12 20 34) 
66.0 


The CLISP: statement is converted to a comment of a special form that is 
represented by CLISP. Whenever a CLISP transformation that is affected by 
declarations is about to be performed, this comment is searched for a relevant 
declaration. If one is found, the corresponding function will be used. Otherwise, 
the global declaration currently in effect will be used. Note that local declara- 
tions are effective in the order in which they are given within the CLISP: form. 


23.2.6 Operator Definitions 


The CLISP operators are defined via properties attached to the atoms represent- 
ing those operators. Thus, CLISP acts as a table-driven system. The definitions 
of the operators are given below. 


«-(GETPROPLIST '+) 
(CLISTYPE 2 LISPFN IPLUS CLISPCLASS + CLISPCLASSDEF 


(ARITH IPLUS FPLUS PLUS) ) 
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“(GETPROPLIST '-) 
(CLISPTYPE 7 LISPFN IMINUS UNARYOP T CLISPCLASS- 
CLISPCLASSDEF (ARITH IMINUS FMINUS MINUS) ) 


+(GETPROPLIST '*) 


(... CLISPTYPE 4 LISPFN ITIMES CLISPCLASS * CLISPCLASSDEF 
(ARITH ITIMES FTIMES TIMES) ) 


where the ... indicates that there are other properties not associated with CLISP. 


*-(GETPROPLIST '/) 
(CLISPTYPE 4 LISPFN IQUOTIENT CLISPCLASS / CLISPCLASSDEF 
(ARITH IQUOTIENT FQUOTIENT QUOTIENT) ) 


«(GETPROPLIST ') 
(CLISPTYPE 6 LISPFN EXPT) 


*-(GETPROPLIST '=) 
(CLISPTYPE -20 LISPFN EQ CLISPNEG =) 


Note: You may want to redefine the value of LISPFN to be EQUAL (see my 
note in Chapter 6). 


«-(GETPROPLIST 'GT) 

(CLISPTYPE -20 LISPFN IGREATERP CLISPCLASS GT 
CLISPCLASSDEF (ARITH IGREATERP FGTP GREATERP) CLISPNEG 
LEQ BROADSCOPE T CLISPISPROP (gt) CLISPISFORM ((X Y) (X 
Is GT ¥)) {% GT Y))) 


*-(GETPROPLIST 'LT) 

(CLISPTYPE -20 LISPFN ILESSP CLISPCLASS LT CLISPCLASSDEF 
(ARITH ILESSP LESSP LESSP) CLISPNEG GEQ BROADSCOPE T 
CLISPISPROP (1t) CLISPISFORM ((X Y) (X IS LT Y) (X LT 


Y))) 


«-(GETPROPLIST 'GE) 
(CLISPTYPE -20 LISPFN IGEQ CLISPCLASS GEQ CLISPCLASSDEF 
(ARITH IGEQ GEQ GEQ) BROADSCOPE T) 


«-(GETPROPLIST 'LE) 
(CLISPTYPE -20 LISPFN ILEQ CLISPCLASS ILEQ CLISPCLASSDEF 


(ARITH ILEQ LEQ LEQ) BROADSCOPE T) 


<-(GETPROPLIST 'MEMBER) 

(CLISPTYPE -20 CLISPNEG MEMBER BROADSCOPE T CLISPISPROP 
(member MEMBERS members) CLISPISFORM ((X Y) (X IS A 
MEMBER OF Y) (MEMBER X Y))) 


and similarly for EQUAL, AND, OR, NOT, and several other INTERLISP 
functions. 
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«(GETPROPLIST ':) 
(CLISPTYPE (14 . 13)) 


*-(GETPROPLIST '+-) 
(CLISPTYPE (* . -12) LISPFN SETQ) 


*-(GETPROPLIST '<) 
(CLISPTYPE BRACKET UNARYOP T CLISPBRACKET (< ) SEPARATOR 
! DWIMIFY CLISPANGLEBRACKETS CLISPIFY SHRIEKIFY) ) 


The properties and values appearing in these examples will be described in 
more detail in later sections. 


23.3 CONDITIONAL STATEMENTS 


CLISP provides conditional structured programming constructs similar to ex- 
tended Fortran or C. These constructs use the operators IF, THEN, ELSEIF, 
and ELSE to demarcate the segments of a conditional expression. 

The format of a CLISP conditional statement is 


(IF {predicate-expression-1) 
THEN « consequent-expression-1) 
ELSEIF {predicate-expression-2) 


THEN {consequent-expression-2) 
ELSE { consequent-expression-3) ) 


The general statement form will be translated into a COND expression of 
the form 


(COND 
(<predicate-expression-1) 
{consequent-expression-1) ) 
(<predicate-expression-2) 
{ consequent-expression-2) ) 
(T <consequent-expression-3)) ) 


Conditional statements may be nested as deep as you wish. The predicate 
and consequent expressions may be any CLISP or INTERLISP expression. 

Conditional statements translate into the standard COND expressions. 
Consider the following function definition: 


(DEFINEQ ‘ 
(to? (node attribute)’ 
(PROG (offspring) 
(if 
offspring (GETPROP node 'offspring) 
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then 
(RETURN 
(CDR 
(ASSOC 
(CAR (get.inheritance node 
attribute) ) 


offspring) ) ))) 
)) 


would be translated as 


(DEFINEQ 
(to? (node attribute) 
(PROG (offspring) 
(COND 
((SETQ offspring (GETPROP node 
'offspring) ) 
(RETURN 
(CDR 
(ASSOC 
(CAR (get.inheritance node 
attribute) 


‘5 offspring) ))))) 


In general, the following translations from INTERLISP to CLISP will be 
observed: 


IF <x) THEN <y) (COND 
(<x) <y))) 
IF <x) THEN <y) ELSE <z) (COND 
(<x) <y)) 
(T <z))) 


If there is nothing following a THEN or the THEN expression is omitted 
entirely, the clause will only consist of a predicate expression. You may use 
lower-case versions of the words IF, THEN, ELSE, and ELSEIF if you prefer. 

You may use DWIMIFY (see Section 22.5) to perform the translations from 
CLISP to INTERLISP and CLISPIFY (see Section 23.8) to translate from IN- 
TERLISP to CLISP. Consider the following examples: 


«-(DWIMIFY '(IF X THEN Y)) 
(COND 
(X Y)) 
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+-(DWIMIFY '(IF X THEN Y ELSEIF X1 THEN Y2 ELSE J3)) 
(COND 

(X Y) 

(X1 Y1) 

(T J3)) 


23.4 ITERATIVE STATEMENTS 


The major power of CLISP is concentrated in allowing the user to write a wide 
variety of iterative expressions. CLISP supports iterative statements that model 
all of the popular constructs of traditional programming languages as well as a 
few new variations. 

CLISP iterative statements are usually translated to either a PROG or 
MAPCAR expression. The specific form used depends on the iterative statement 
operators (called i.s.oprs) and the manner in which they are combined. When it 
translates an iterative expression, CLISP often inserts dummy variables (de- 
noted by preceding $$) as control mechanisms. You will see these dummy vari- 
ables when you display functions after translation. 

For all of the following operators, lower-case versions may be used and will 
be treated by CLISP as equivalent to the upper-case versions. Lower-case words 
will improve the readability of your code. 

Each iterative statement operator has lower precedence than all IN- 
TERLISP forms. Thus, parentheses around the operands may be omitted. 
CLISP will provide the parentheses internally during the translation process. 


23.4.1 1.$.Opr Translation 


The exact form of an iterative statement translation depends on the operators 
used in the expression. If the expression specifies dummy variables (such as: in Y 
as I from 1 to 10 do PRINT), a PROG will always be used. The general form, 
using a PROG, is 


(PROG {variables) 
[initialization] 
$$LP 
[eachtime ] 
[test] 
[body] 
$$ITERATE 
[aftertest] 
[update] 
(GO $$LP) 
$$OUT 
[finalization] 
(RETURN $$VAL) ) 





SSS 





SOS 


—= 


SSeS SES 
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where the following conditions hold: 


1. [initialization] is a sequence of expressions that assign initial values to 
the loop variables. 

2. [eachtime] is a sequence of expressions executed each time through the 
loop that set up the conditions for this iteration. 


3. [test] is a sequence of expressions that test for loop termination before 
execution of the [body]. 


4. [body] is a sequence of expressions forming the main function to be per- 
formed by the loop. 
[aftertest] is a sequence of expressions that test for termination after loop 


execution. They correspond to the REPEATWHILE or REPEATUNTIL 
conditions. 


5 


6. [update] is a sequence of expressions that increment or otherwise com- 
pute new values for the loop variables. 

7. [finalize] is a sequence of expressions that compute a final value prior to 
exiting the loop. 


$$LP, SSITERATE, and $$OUT are consistently used in all translations. 
You may reference them within your CLISP statements. You may also explicitly 
set or reference the variable $$VAL which contains the value to be returned as 
the result of the loop. 


23.4.2 1.8.Type Operators 


An iterative statement type operator is one that specifies the action to be taken 
on each iteration. I.s.type operators have a body composed of other iterative 
statement operators. Each iterative statement must have one and only one 
i.s.type operator. The i.s.type operators are 


DO <form) Specifies what is to be done at each 
iteration. Its value is NIL if there is 
an explicit or implicit terminating 
condition. DO without another operator 
specifies an infinite loop (because 
there is no terminating condition!). It 
translates to MAPC or MAPCAR whenever 


possible. 
(FOR y IN (CDR x) 
DO 
(if 
y:l = '* 
then 


(PRIN1 '**) 
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else 
(PRIN1 y:1) 
(SPACES 1)) 
(PRIN1 (CDR y)) 
(SPACES 1)) 


Transaction processing programs usually have the 
form of a continuous loop that performs the actions 
of reading a command, executing the command, and 
printing the results (just like the INTERLISP 
intepreter). The structure of such a program might 


appear as 
(DO 
(read.command) 
(if 
(execute. command) 
then 
(print.results) 
else 
(GO exit) )) 
OX1T 4 sas 


COLLECT <form) Specifies that the result of evaluating 
<form) at each iteration is to be 
collected into a list which is returned 
as the value of the expression. It is 
translated to MAPCAR, MAPLIST, or 
SUBSET as appropriate. 


Consider a function which may take either a single 
atom or a list of atoms as an argument. If a list of 
atoms is given, the results of the function must be 
collected into a list to be returned as its value. 
Here is a fragment from GETFILEPKGTYPE: 


(FOR x IN type 


COLLECT 
(OR 
(getfilepkgtype x 
only 
noerror 
name ) 
(RETURN) ) ) 


which translates to 


(PROG (($$LST1 TYPE) 
$$VAL $$TEM2 $$TEM1 X) 
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$$LP 
(SETQ X 
(CAR (OR (LISTP $$LST1) 


(GO $$0UT)))) 
(SETQ $$TEM1 


(OR 
(GETFILEPACKAGETYPE X 
ONLY 
NOERROR 
NAME) 
(RETURN) ) ) 
(COND 
($$TEM2 
(FRPLACD $$TEM2 
: (SETQ $$TEM2 (LIST $$TEM1)))) 
T 
(SETQ $$VAL 
(SETQ $$TEM2 (LIST $$TEM1) )))) 
$$ITERATE 
(SETQ $$LST1 (CDR $$LST1) ) 
(GO $$LP) 
$$OUT 
(RETURN $$VAL) ) 


JOIN <form) Specifies that the values resulting 
from the evaluation of <form) will be 
NCONCed together. It translates to 
MAPCON or MAPCONC as appropriate. 


GETDEF returns the definition of a name as a type from a 
file. Consider the following fragment which is used to 
process the type MACROS: 


(MACROS 
(CONS 'PUTPROPS 
(CONS name 
(OR (FOR x on (GETPROPLIST name) 
BY (CDDR x) 
WHEN 
(MEMBER (CAR x) MACROPROPS) 
JOIN 


(LIST (CAR x)(CADR x))) 
(GETDEFERR NIL name type options) )))) 


SUM <form) Specifies that the values resulting 
from the evaluation of <form) at each 
iteration should be added together. 
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The IRM suggests that you can define the sum of squares 
as follows: 


<— (DEFINEQ 
(sum.of.squares (n) 
(FOR i FROM 1 to n SUM (ITIMES i i)) 
)) 
(SUM.OF.SQUARES) 


which, when executed for N.equal to 7 would yield the sum 
of 1+4+9 +16 + 25 + 36 + 49 or 140. 


<—(sum.of.squares 7) 


a, a 


140 
COUNT <form) Counts the number of times that the 
result of evaluating <form) is true. 
Suppose I have a vector of numbers whose values represent . 
the closing value of the New York Stock Exchange for ; 


1982. I want to find on how many days the market closed 
above 1200. I could do so using the following expression: 


(FOR i from 1 to 365 . 
COUNT (GREATERP (ELT nyse.close i) 1200.0)) ; 


ALWAYS <form) Returns T if every evaluation of <form) 
is true; otherwise, it returns NIL as 
soon as NIL is the result of the 
evaluation. It is equivalent to 


(EVERY x (FUNCTION <fn))) 


The form (ALWAYS X) is translated as follows: 
(PROG (($$VAL T)) 
$$LP 
(COND 
((NULL X) 
(SETQ $$VAL NIL) 
(GO $$0UT) ) ) 


oeko are <qrres 


| 
; 
. 
| 
4 


$$ITERATE 
(GO $$LP) 

$$OUT 
(RETURN $$VAL) ) 


NEVER <form) Returns T if every evaluation of <form) 
is NIL; otherwise, it returns T as soon 
as T is the result of the evaluation. 
It is equivalent to 


ALWAYS" <form) 
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or 
(NOTANY y (FUNCTION <fn))) 


THEREIS <form) Returns the first value of the 
iteration variable for which the result 
of evaluating <form) is non-NIL. It is 
equivalent to 


(CAR 
(SOME y (FUNCTION <fn)))) 


23.4.3 1.S.Binding Operators 


An iterative statement binding operator binds the iteration variable for the itera- 
tion. These operators are 


FOR <var) Specifies the variable of iteration 
which is used with an i.s.selection 
operator. The variable is rebound (if 
it has the same name as some external 
variable) for the scope and duration of 
the iterative statement unless OLD is 
specified. 


FOR <vars) <vars) is a list of variables, the first of 
which is the iteration variable, while 
the rest are dummy variables. 


Consider the following example from 
GETDEFFROMFILE which tries to get a 
definition from a source file. 


(DEFINEQ 
(getdeffromfile (name type source options) 
(RESETVARS 

(NOT-FOUND-TAG) 

(RETURN 
(FOR file def temp temp2 
INSIDE 

(COND 


((EQ source 'file) 
(WHEREIS name type T)) 
(T source) ) 
WHEN 
(AND ... 


where TEMP and TEMP2 are bound within various cases in 
the AND ... clause. 
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OLD <var) Specifies that the variable is not to 
be rebound, e.g., reuse a variable that 
you have already used. 


Consider the example: 


(FOR OLD (SETQ X <expression)) 
BIND (SETQ Y <expression) ...) 
BIND <var) Used to specify dummy variables or BIND 
<vars) to make a variable local to an 
expression. 


23.4.4 1.8.Selection Operators 


An iterative statement selection operator assigns a value to the iteration variable 
at each iteration. These operators are used with i.s.type operators described 
above. 


IN <form) Specifies that the iteration variable 
is set to successive elements of the 
value resulting from the evaluation of 
the form. If no iteration variable has 
been specified, a dummy will be 
supplied. 


Consider the following example: 


<-(DWIMIFY '(FOR X IN Y JOIN X Y)) 





(MAPCONC Y 
(FUNCTION 
(LAMBDA (X) 

X 

Y))) 
IN OLD <var) Specifies that the iteration variable 

is reset to its tail at each iteration. 

ON <form) Specifies that the iteration variable 


is reset to the corresponding tail at 
each iteration. 


ON OLD <var) Specifies that the variable is reset to 
its current value at the end of each 
iteration (where it is assumed that the 
variable is set in the body of the 
expression). 
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INSIDE <form) Specifies that the iteration proceeds 
until the first non-list, non-NIL 
element of the form is encountered. 


Consider the following example from INFILEPAIRS in the File Package: 


(FOR 11 IN lst 
DO 
(FOR x INSIDE (CAR 11) 
DO 
(FOR y INSIDE (CDR 11) 
DO 
INFILECOMSVAL (LIST x y)))) 


where the INSIDE expression translates to 


(PROG ($$VAL X ($$TEM1 (CAR LL) )) 
$$LP 
(COND 
((NULL $$TEM1) 
(GO $$0UT) ) 
((NLISTP $$TEM1) 
(SETQ X $$TEM1) 
(SETQ $$TEM1 NIL) ) 
(T 
(SETQ X (CAR $$TEM1) ) 
(SETQ $$TEM1 (CDR $$TEM1) ))) 
(INFILECOMSVAL (LIST X Y)) 
$$ITERATE 
(GO $$LP) 
$$0UT 
(RETURN $$VAL) ) 


FROM <form) Specifies an initial value for a numerical 
iteration variable. The iteration variable 
will automatically be incremented by 1 
after each iteration (if no BY clause is 
specified). If no iteration variable is 
specified, a dummy variable is supplied and 
initialized in the translation. 


TO <form) Specifies the final value for a numerical 
iteration variable. The iteration 
terminates when the value of the iteration 
variable exceeds the value resulting from 
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the evaluation of the form (unless some 
other termination condition is met first). 


BY <form) If used with an IN/ON clause, the value 
resulting from the evaluation of the form 
determines the tail of the next iteration. 
The new value of the iteration variable is 
the CAR of the tail for IN or the tail 
itself for ON. 


BY <form) If used without IN/ON, the value resulting 
from the evaluation of the form specifies 
how the iteration variable is set at each 
iteration. The iteration variable is 
assumed to be numeric. The new iteration 
variable value is computed by adding the 
value of the evaluation of form at each 
iteration to the current value of the 
iteration variable. 


Consider the combined example for the three operators described above: 


«<(DWIMIFY '(FOR X FROM 1 TO 20 BY 2 DO (PRINT X))) 
(PROG (($$TEM1 20) 

$$VAL 

(X 1)) 


(COND 
((IGREATERP X $$TEM1) 
(RETURN $$VAL) )) 
(PRINT X) 
$$ITERATE 
(SETQ X (IPLUS X 2)) 
(GO $$LP) ) 


$$LP 


AS <variable) Specifies an iterative statement involving 
more than one iterative variable. The 
iterative statement terminates when any of 
the terminating conditions are met. The 
argument, (variable), specifies the new 
iterative variable. For the remainder of 
the statement or until another AS is 
encountered, all operators will apply to 
the new iterative variable. Consider the 
example (after the IRM) 
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(FOR I FROM 1 TO N1 
AS J FROM 1 TO N2 BY 2 
AS K FROM N3 TO 1 BY -1 ...) 


23.4.5 1.$.Termination Operators 


An iterative statement termination operator specifies a condition for terminating 
the iteration. The effect of these operators takes precedence over the termination 
conditions given by IN/ON ... FROM ... TO... BY clauses. 


WHEN <form) The i.s.type operator will be executed 
only if the condition resulting from 
the evaluation of the form is true. 


Consider the following translation: 


*-(DWIMIFY '(FOR X IN Y COLLECT X WHEN (NUMBERP X))) 
(SUBSET Y (FUNCTION NUMBERP) ) 


UNLESS <form) The i.s.type operator is executed 
except when the condition resulting 
from the evaluation of form is true. 
It is equivalent to WHEN "<form). 


Consider the following translation: 


«(DWIMIFY '(FOR X IN Y COLLECT X UNLESS (NUMBERP X))) 
(SUBSET Y 
(FUNCTION 
(LAMBDA (X) 
(NOT (NUMBERP X))))) 


WHILE <form) The i.s.type operator is executed as 
long as the value resulting from the 
evaluation of form is true. The form 
is evaluated before each iteration. A 
NIL result terminates the iteration. 
The test is performed before each 
iteration. 


UNTIL <form) The i.s.type operator is executed as 
long as the value resulting from the 
evaluation of the form is NIL. It is 
equivalent to WHILE '"<form). 
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If <form) is a number, then the 
iteration terminates when the value of 
the iteration variable is greater than 
the number. 


(UNTIL <x)) would translate as 


(PROG ($$VAL) 
$$LP 
(COND 
(<x) (RETURN $$VAL))) 
$$ITERATE 
(GO $$LP) ) 


REPEATWHILE <form) Like WHILE, except that the test is 
performed after the iteration, but 
before the iteration variable is reset 
so that you may test the value of the 
iteration variable. 


REPEATUNTIL <form) Like UNTIL, except that the test is 
performed after the evaluation of the 
body of the iteration, but before the 
iteration variable is reset so that 
you may test the value of the 
iteration variable. 


If <form) is a number, then the 
iteration terminates when the value of 
the iteration variable is greater than 
the number. 


23.4.6 1.S.Modification Operators 


An iteration statement modification operator modifies the execution of the itera- 
tion statement or the value(s) produced by its execution. 


FIRST <form) The form is evaluated once before the 
first iteration. It is often used to 
initialize dummy variables (see BIND). 
Consider the example (after the IRM) 


(FOR X Y Z IN LST 
FIRST (INITIALIZE Y Z) ...) 


FINALLY <form) The form is evaluated after the 
iteration terminates. 
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Ex: The IRM suggests the following example for counting the number of 
atoms in a list: 


(FOR x IN ist 
BIND yO 
DO 
(IF ATOM x THEN y+y+1) 
FINALLY (RETURN y)) 


EACHTIME <form) The form is evaluated before each 
iteration. It is often used to assign 
values to temporary variables or 
perform other computations which may 
be used in several places in the body 
of the iteration. 


DECLARE <decl) Used to insert a declaration after the 

DECLARE: <decl) PROG variable list in the translation 
or after the LAMBDA expression in a 
mapping function. Usually used to 
specify local or special variables for 
expressions that will utlimately be 
compiled. 


ORIGINAL <i.s.opr) Specifies that the original, built-in 
interpretation of the iterative 
statement operator will be used rather 
than any user-defined interpretations 
of it. 


Each of these operators may have operands that consist of multiple expres- 
sions. In the translation, a PROGN will be supplied to handle the multiple oper- 
ands. 


23.4.7 Potential Errors in Iterative Statements 


The flexibility of the I.S.OPRs also provides opportunities for generating erro- 
neous expressions. Some pitfalls to watch out for include 


1. Operators with null operands, as evidenced by two adjacent operators in 
an expression: 


«-(DWIMIFY '(FOR X IN Y UNTIL DO (CONS X X))) 
error in iterative statement, 

missing operand: 

... UNTIL ... DO (CONS X X) 
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2 


Operands consisting of more than one form (except as explicitly allowed 
for the i.s.modification operators: 


<(DWIMIFY '(FOR X IN Y (PRINT X) COLLECT X)) 
error in iterative statement, 
cae. (¥ CPRINT X))) «2. COLLECT XZ 


3. IN, ON, FROM TO, or BY appear twice or more in the same iterative 
statement: 


<-(DWIMIFY '(FOR X IN Y AND A IN B DO COLLECT X A)) 
error in iterative statement, 
operator appears twice: 

. IN Y AND A IN B DO COLLECT X A 


4. Both IN and ON used on the same iterative variable: 


<(DWIMIFY '(FOR X IN Y AND A ON Y DO COLLECT X A))) 
error in iterative statement, 
can't use both of these operators together: 

. IN Y AND A ON Y DO COLLECT X A 


5. FROM or TO used with IN or ON on the same iterative variable: 


<(DWIMIFY '(FOR X IN Y DO FROM 1 TO Y (ADD1 X))) 
error in iterative statement, 
can't use both these operators together: 

. IN Y DO FROM 1 TO Y (ADD1 X)) 


6. Missing DO, COLLECT, or JOIN: 


<(DWIMIFY '(FOR X IN Y (ADD1 X))) 
(MAPC Y (FUNCTION ADD1)) 


where CLISP has inserted a DO after Y. On the other hand, consider 
<(DWIMIFY '(FOR X IN Y CONS X)) 
No DO, COLLECT, or JOIN in: 
(FOR X IN (Y CONS X)) 
7. No terminating condition is detected: 
<(DWIMIFY '(FOR X FROM 1 BY 3 DO (PRINT X))) 


Possible non-terminating iterative statement: 
(FOR X FROM 1 BY 3 DO (PRINT X)) 
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(PROG ($$VAL (X 1)) 
$$LP 
(PRINT X) 
$$ITERATE 
(SETQ X (IPLUS X 3)) 
(GO $$LP) ) 


where there is no way to terminate the PROG loop. 


The iterative statement is still translated because you may terminate the 
statement from within a function invoked in the statement by a RETFROM, by 
inducing an error (such as in the Editor), or executing (CTRL-E). 

When an erroneous condition is detected, a diagnostic message will be 
printed unless CLISP.I.S.GAG is T. It is initially NIL. When an error occurs, 
the iterative statement is not changed (e.g., translated). 


23.4.8 Defining New Iterative Statement Operators 


You may define a new I.S.OPR or redefine an existing one using I.S.OPR. It 
takes the form 


Function: I.S.OPR 
# Arguments: 4 


Arguments: 1) an i.s.opr name, NAME 
2) an expression, EXPRESSION 
3) an optional list of i.s.oprs, OTHERS 
4) an evaluation flag, EVALFLAG 


Value: The name of the new i.s.opr. 


If EXPRESSION is a list, then NAME is the name of the new i.s.opr and 
EXPRESSION is its body, e.g., its translation. For example, we might define 
GATHER similarly to COLLECT as follows: 


«-(1I.S.OPR 'GATHER '(SETQ $$VAL (NCONC1 $$VAL BODY) )) 
GATHER 


<-(DWIMIFY '(FOR X IN Y GATHER X)) 
(PROG (($$LST1 Y) 
$$VAL X)) 
$$LP 
(SETQ X 
(CAR (OR (LISTP $$LST1) 
(GO $$0UT) ))) 
(SETQ $$VAL (NCONC1 $$VAL X)) 
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$$ITERATE 
(SETQ $$LST1 (CDR $$LST1)) 
(GO $$LP) 

$$OUT 
(RETURN $$VAL) ) 


The IRM notes that you may define the following versions of COLLECT that 
use different functions: 


(I.S.OPR 'RCOLLECT 
'($$VAL@ (CONS BODY $$VAL) ) 
'(FINALLY (RETURN (DREVERSE $$VAL) ))) 


RCOLLECT uses CONS instead of NCONC1 and reverses the values that it 
collects. Here, OTHERS is an list of additional i.s.operators and operands that 
will be inserted in the iterative statement where NAME appears. 

EXPRESSION may be NIL, whence the new i.s.opr is defined by OTHERS. 


(I.S.OPR 'TCOLLECT 
'(TCONC $$VAL BODY) 
‘(FIRST $$VAL@ (CONS) FINALLY (RETURN (CAR 
$$VAL) ))) 


In EXPRESSION and OTHERS, you may use the atom $$VAL to refer to 
the value returned by the iterative statement. You may use I.V. to refer to the 
current iterative variable. And you may use BODY to refer to the operand of 
NAME. 

If EVALFLAG is T, EXPRESSION and OTHERS are evaluated at transla- 
tion time and the value is used in the translation. This allows you to vary the 
translation for the same i.s.opr depending on conditions within your program. 

You may save new I.S.OPRs that you have defined using the File Package 
command I.S.OPRS (see Section 17.2.15). 


23.5 ENGLISH PHRASES 


One objective of CLISP is to make INTERLISP code more readable. To this 
end, it accepts a limited number of English-like constructions of the form 
“subject is <object)”. 


NROWS is a NUMBER 
(MAKEFILENAME x) is not a STRING 


Both the subject and the object may be distributed: 


XWORD AND TWORD ARE ATOMIC 
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means 
XWORD IS ATOMIC and TWORD IS ATOMIC 


CLISP converts INTERLISP expressions into “‘english’’ when CLISPI- 
FYENGLSHFLG is T. 


23.5.1 Basic English Forms 


CLISP knows about a set of English words in both their singular and plural 
forms. This set includes 


ARRAY ATOM ATOMIC FLOATING POINT NUMBER 
LIST LITATOM NIL LITERAL ATOM 

NULL NUMBER STRING SMALL INTEGER 

EQ TO EQUAL TO GEQ SMALL NUMBER 

GT LT MEMB OF GREATER THAN 


TAIL OF MEMBER OF LESS THAN 
Any relationship may be negated by using NOT or N’T: 


(CADR NAME) AND (CDDR Y) AREN'T LISTS. 


23.5.2 Defining New Words 


You may expand the lexicon used by CLISP using the function NEWISWORD, 
which takes the form 


Function: NEWISWORD 
# Arguments: 4 


Arguments: 1) a singular form, SING 
2) a plural form, PLURAL 
3) a translation form, FORM 
4) the form parameters, VARS 


Value: The name of the new word that will be 
recognized by CLISP. 


For example, the IRM notes that you may define the phrase SMALL INTE- 
GER using the following expression: 


<— (NEWISWORD 
'(X IS A SMALL INTEGER) 
'(ARE SMALL INTEGERS) 
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'(SMALLP X) 
'(X)) 
SMALL 


«(DWIMIFY '(5 IS A SMALL INTEGER) ) 
(SMALLP 5) 


«(5 IS A SMALL INTEGER) 
5 


Note that the plural form does not include the subject. 

The ability to define new words for CLISP translations allows you to extend 
your interactive environment to accommodate new sentences. In fact, you may 
define a subset of English using appropriate NEWISWORD and I.S.OPR defi- 
nitions that will make your programs much more accessible. 


23.6 CLISPIFYING 


CLISPIFY is a function that converts an INTERLISP expression to CLISP nota- 
tion. It takes the form 


Function: CLISPIFY 

# Arguments: 2 

Arguments: 1) an expression, EXPRESSION 
2) an optional list, LST 

Value: The translation of EXPRESSION. 


If EXPRESSION is an atom and LST is NIL, EXPRESSION is assumed to 
be the name of a function. CLISPIFY operates on its definition (via GETD) or 
its EXPR property value. After CLISPIFYing, EXPRESSION is redefined via 
/PUTD with its new CLISP definition. 

If EXPRESSION is atomic, but not the name of a function, CLISPIFY at- 
tempts to correct its spelling. If this is successful, it proceeds as above. One 
wise, an error is generated. 


<(CLISPIFY '(PROG (X) (COND ((NULL X) (SETQ X (CAR Y))) 
(T (PRINT X))))) 
(PROG (X) (if X=NIL then X*-Y:1 else (PRINT X))) 


If X is an S-expression and LST is not NIL, X will be translated to CLISP 
notation. LST is an edit push-down list that provides a context for DWIMIFY- 
ing the expression. 


«(CLISPIFY '(itimes x y)) 
(xy) 
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23.6.1 CLISPIFY Variables 
CLISPIFY operation is affected by the values of several global variables. 


eae 


a ae 





CL:FLG Affects the translation of CAR, CDR, 
CADR, ..., CDDDDR to the corresponding 
infix notation using the : operator. If 
CL:FLG is T, simple expressions where 
the argument is atomic or a simple list 
will be converted to : notation. If 
CL:FLG is ALL, every possible 
conversion to : notation will be made. 
For example, 


«-(SETQ nfl.coaches '(gibbs landry grant stram) ) 
(gibbs landry grant stram) 


«(SETQ CL:FLG T) 
T 


<(CLISPIFY '(SETQ retired.coaches (CADR nfl.coaches) )) 
(retired.coaches«nfl.coaches: :2) 


CLREMPARSFLG Affects the removal of parentheses from 
simple expressions in order to improve 
their readability. It initially has the 
value NIL. For example, 


«-(SETQ CLREMPARSFLG T) 
7 


<(CLISPIFY '(COND ((ATOM X) (LIST X)) ((LISTP X) X) (T 


(CONS X NIL)))) 
(if ATOM X then X elseif LISTP X then X:1 else (CONS X 


NIL) ) 


CLISPIFYPACKFLG Affects the form of the translation for 
atomic operands. If its value is T, a 
translation involving infix operators 
can be packed into a single atom. For 
example, 


«(SETQ CLISPIFYPACKFLG NIL) 
NIL 


«-(CLISPIFY '(ITIMES X Y)) 
(X * Y) 
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+-(SETQ CLISPIFYPACKFLG T) 
T 


«-(CLISPIFY '(ITIMES X Y)) 
(X*Y) 


CLISPIFYENGLSHFLG Affects the production of English 
phrases. When it is T, CLISPIFY 
translates INTERLISP expressions into 
their corresponding English phrases 
using either the SYSHASHARRAY or 
CLISPARRAY. For example, 


«(SETQ CLISPIFYENGLSHFLG T) 
T 


<(CLISPIFY '(COND ((ATOM X) X) ((LISTP X) (CAR X)) (T 
(PRIN1 X)))) 

(ATOM X) then X elseif (LISTP X) then X:1 else (PRIN1 
X 


FUNNYATOMLST Allows CLISP to avoid conflicts between 
its translations and atoms defined by 
the user. For example, if you have 
defined atoms of the form X, Y, and X*Y 
(a legal atom!), then 


<-(CLISPIFY '(ITIMES X Y)) 
X*Y 


which conflicts with a variable name. 
You may prevent this conflict by adding 
the atom X*Y to FUNNYATOMLST. CLISPIFY 
will produce 


<(SETQ funnyatomlst (LIST 'x*y)) 
(xy) 

<(CLISPIFY '(ITIMES X Y)) 

(X * Y) 


Note: You should avoid using CLISP operators as 
components of variable names. In general, there is no 
reason to use such meaningless variable names when you 
have the ability to make variable names mnemonically 
interesting. 
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CLISPIFYPRETTYFLG Affects the prettyprinting of all 


expressions. If its value is T, 
PRETTYPRINT invokes CLISPIFY on all 
expressions before printing them. 
MAKEFILE (see Section 17.3.1) 
automatically sets CLISPIFYPRETTYFLG to 
T before writing expressions to a file. 


It takes the following values: 


ALL Apply to all functions 


T.EXPRS Apply to functions that are 
currently defined as EXPRs 


CHANGES Apply to functions that have 
been marked as changed 


(list) Apply only to functions that 
are mentioned in the list 


23.7 CLISP CONVENTIONS 


CLISP acts like a table-driven translator. Each operator has properties which 
describe how its translation is to be affected. You may add new operators or 
redefine existing operators by modifying the values of properties associated with 
those operators. CLISP uses the following properties: 


CLISPTYPE 


This property is the precedence of the 
operator. It defines how the operator will 
be translated relative to other operators. 
The actual value is not important, only its 
value relative to other operators. The value 
may be a number, a dotted pair, or an 
expression to be evaluated. 


An operator may have different left and 
right precedence by setting the value of 
CLISPTYPE to a dotted pair of two numbers. 
For example, the precedence of « is the 
dotted pair (8. -12). The CAR of the dotted 
pair is the left precedence while the CDR is 
the right precedence. The IRM notes that 
AXB<-C+D is parsed as A*(B*#-(C+D)) because 
the left precedence of « is 8 while that of 
* is 4, but its right precedence is -12 
which is lower than that of + which is 2. 
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UNARYOP 


BROADSCOPE 


LISPFN 


SETFN 


CLISPINFIX 


The precedences of the CLISP operators are 
given in Section 23.2.4. 


Removing the precedence of a CLISP operator 
disables the corresponding transformation 
(see CLDISABLE). 


This property with value T declares the 
operator to be a unary operator. Its operand 
must always be to its right in the 
expression. 


This property with value T declares that the 
operator has lower precedence than INTERLISP 
forms. For example, (FN1 X AND Y) would be 
translated as ((FN1 X) AND Y) if the 
BROADSCOPE property for AND is T, but (FNi 
(X AND Y)) otherwise. 


This property has as its value the INTERLISP 
function to which the operator will be 
translated. The translations for the CLISP 
operators are given in Section 23.2.6. 


If LISPFN is NIL, the operator is also the 
function itself. For example, AND is both a 
CLISP operator and the corresponding 
function. . 


If an operator has a SETFN property, then an 
expression of the form 


(<op>) ...) < expression) 


will be translated to an expression that 
sets the corresponding values. 


For example, you may make # be a CLISP 
operator equivalent to the function ELT (see 
Section 11.2.6) by putting the CLISPTYPE 
property on its property list. If you put a 
SETFN property on the property list of #, 
expressions of the form X#N « Y will be 
translated to (SETA X NY). 


This property is used when translating 
INTERLISP forms to infix notation. This 
property resides on the property list of the 
INTERLISP function. For example, 








CLISPWORD 


CLISPBRACKET 
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«-(GETPROP 'EXPT 'CLISPINFIX) 
* 


<-(GETPROP 'TIMES 'CLISPINFIX) 
(CLISPINFIX *) 


This property is associated with CLISP 
operators that may be the CAR of an 
expression. Its form is 


(<keyword) . <name)) 


where (name) is the lower-case version of 
the operator and <(keyword) is its type. 


*-(GETPROP 'FETCH 'CLISPWORD) 
(RECORDTRAN . fetch) 


(keyword) may also be a function. When the 
atom appears as the CAR of an expression, 
the function is either applied to the 
expression to change the expression or calls 
CLISPTRAN to store a translation. 


This property defines new bracket operators. 
It must appear on the property list of both 
the left and right brackets. 


The property must also appear on the 
property list of any functions that the 
expressions involving the brackets will 
translate to. The value of the property in 
this case is a list whose CAR is the left 
bracket symbol, whose CADR is the right 
bracket symbol, and whose CDDR is a list in 
property list format which may include the 
properties 


DWIMIFY Value is a function to be 
called to DWIMIFY the 
construct. It is given the 
DWIMIFYed expression bounded 
by the brackets. 


CLISPIFY Value is the function to be 
called when CLISPIFYing the 
construct. 
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SEPARATOR Value is a character to be 
split from any atoms, but 
otherwise unprocessed. For 
example, for ¢ and ) the 
separator is !. 


To define [ and ] as brackets which translate to ELT in 
the case of a single expression and ELTM for more than 
one: 


«-(PUTPROP '[{ 'CLISPTYPE 'BRACKET) 
BRACKET 


«-(PUTPROP '] 'CLISPTYPE 'BRACKET) 
BRACKET 


«-(PUTPROP '[ 'CLISPBRACKET '({ ] (SEPARATOR NIL 
DWIMIFY FOO) ) 
'({ ] (SEPARATOR NIL DWIMIFY FOO) ) 


| ©(PUTPROP '] 'CLISPBRACKET '({ ] (SEPARATOR NIL 
DWIMIFY FOO)) 
'({ ] (SEPARATOR NIL DWIMIFY FOO)) 


+ (DEFINEQ 
(FOO (EXPRESSION LST) 
(IF (MEMBER ', LST) 
THEN 
<'ELTM EXPRESSION 
(FOR X IN LST 
COLLECT X 
WHEN X=',))> 
ELSE <'ELT EXPRESSION ! LST)))) 
(FOO) 


+-(NCONC CLISPCHARS '([ ] ,)) 
(T#/te-eert+e=2¢ >) @1)) 


«(SETQ CLISPCHARRAY (MAKEBITTABLE CLIPSCHARS) ) 

{ ARRAYP }]#542224 

Then, X:1[N-1] will dwimify to (ELT (CAR X) (SUB1 N)) and 
Z(N,M] will dwimify to (ELTM ZN M). 

To enable CLISPIFYing, you must define 


«-(PUTPROP 'ELT 'CLISPBRACKET '[) 
[ 








23.8 CLISP Functions 869 
«-(PUTPROP 'ELTM 'CLISPBRACKET ' [) 
[ 


Then, (ELTM (CADR A) (IQUOTIENT (SUB1 N) 2)) I) will 
clispify to A:2[(N-1)/2,I] 


23.8 CLISP FUNCTIONS 


CLISP provides a number of functions that allow you to produce the effect of a 
CLISP translation from within your program or modify the state of your environ- 
ment. 


23.8.1 CLISPIFYing Functions 


CLISPIFYFNS is an NLAMBDA, nospread function that takes a list of one or 
more functions as its argument. It invokes CLISPIFY on each function in the 
list. It takes the form 


Function: CLISPIFYFNS 

# Arguments: 1 

Argument: 1) a function specification, FNS 

Value: A list of functions that have been 
CLISPIFYed. 


CLISPIFYFNS handles the following cases: 


1. If FNS is an atom and is the name of a function, then that function is 
CLISPIFYed. 

2. If FNS is an atom and is not the name of a function, CLISPIFYFNS 
determines if it is the name of a file. If it is, then the list of function given 
by the FNS command in the File Package commands is used as the list of 
functions to CLISPIFY. 

3. If FNS is neither the name of a function nor the name of a file, it gener- 
ates an error. 

4. If FNS is a list, then CLISPIFY is applied to each element of the list. 


If any element of the list does not have a function definition, CLISPIFYFNS 
simply moves to the next element. The application of CLISPIFY is errorset pro- 
tected so that a non-function name in the middle of the list will not cause the 


operation to be terminated. 


870 Conversational LISP 


23.8.2 Disabling CLISP Operators 


You may disable a CLISP operator by executing the function CLDISABLE, 
which takes the form 


Function: CLDISABLE 

# Arguments: 1 

Argument: 1) an operator, OPERATOR 
Value: The operator. 


Disabling a CLISP operator causes the operator to be treated as just another 
character. Consider the following example: 


<5*10 

50 

<-(CLDISABLE '*) 
% 

—5*10 

UNBOUND ATOM 
5*10 


23.8.3 Storing CLISP Translations 


For frequently used expressions, you may cache the CLISP translation of an ex- 
pression for future use by executing CLISPTRAN, which takes the form 


Function: CLISPTRAN 

# Arguments: 2 

Arguments: 1) an expression, EXPRESSION 
2) a translation, TRANSLATION 

Value: The value of the translation. 


CLISPTRAN stores TRANSLATION as the translation of EXPRESSION 
in the hash array CLISPARRAY. CLISPTRAN is usually called by CLISPIFY to 
preserve translations. Consider the following example: 


«+(CLISPTRAN 'X*Y '(ITIMES X Y)) 
(ITIMES X Y) 
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23.9 CLISP VARIABLES 


CLISP uses many global variables to drive the translation process. These vari- 
ables are available for inspection and modification by your programs so that you 
may determine how your program will be translated. 


CLISPFLG Determines when CLISP translations are 
performed. It takes one of three values: 


1. If CLISPFLG is NIL, no CLISP infix or 
prefix translations will take place. 
However, IF/THEN/ELSE and iterative 
statements will not be affected. 

2. If CLISPFLG is TYPE-IN, CLISP 
translations are performed only on 
expressions typed in by you (including 
DEFINEQ expressions), but not on 
existing functions that you have 
already defined. 

3. If CLISPFLG is T, CLISP translations 
are performed on all expressions 
regardless of their origin. 


The initial value of CLISPFLG is T. 


If you CLISPIFY any expression, it will 
leave CLISPFLG set to T (a side effect). 


CLISPARRAY A hash array (see Section 11.3) that is 
used to stored all CLISP translations. 
Both FAULTEVAL and FAULTAPPLY check 
CLISPARRAY for the translation of 
erroneous forms before calling DWIM. 


CLISPHELPFLG If NIL, DWIMIFY (see Section 22.5) will 
not ask your approval for any CLISP 
translations. Instead, it assumes a 
default of "No''. IF CLISP is enabled, this 
flag should be set to T. 


CLISPIFTRANFLG If NIL, CLISP replaces IF/THEN/ELSE 
statements by the corresponding COND 
expressions. If T, the translations are 
stored in a system table. It is initially 


NIL. 
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CLISPRETRANFLG If T, DWIMIFY will (re)translate all . 
expressions having translations stored in 
the hash array or in CLISP% format. It is 
initially NIL. 


CLISPIFYUSERFN If T, its value is applied to each 
expression which is not recognized by 

CLISPIFY. That is, if CLISP does not have 
a translation for an expression, the 
function given by CLISPIFYUSERFN is called 
to deal with the expression. If a non-NIL 
value is returned, it it assumed to be the 
CLISPIFYed expression. 


23.10 THE CHANGETRAN PACKAGE 


The CHANGETRAN Package is a mechanism for expressing, in a shorthand 
notation, some of the more commonly used structure modification operations. 
CHANGETRAN defines a set of CLISP words that encode the kind of modifica- 
tion that will be performed when the word is encountered and translated by IN- 
TERLISP. 


23.10.1 CHANGETRAN Words 


The CHANGETRAN Package defines a set of basic words that are recognized by 
CLISP: 


(ADD (datum) <item1) ... (itemN)) 

The values of the specified items are added to (datum) and the result is stored 
back into (datum). CLISP uses IPLUS, FPLUS, or PLUS depending on the 
CLISP declarations currently in effect. Consider the following examples: 


«(SETQ X 100) 
100 


“(ADD X 25) 
125 


(PUSH (datum) <item1) ... (itemN)) 

The values of the specified items are CONSed onto the front of the current value 
of (datum). The result is stored as the value of (datum). Consider the following 
examples: 


«-(SETQ STACK NIL) 
NIL 
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«(PUSH STACK 'A) 
(A) 

«(PUSH STACK 'B) 
(B A) 


(PUSHNEW (datum) <item)) 

The specified item is CONSed onto the front of the current value of (datum) if 
and only if it is not already a member of (datum)’s value. Consider the following 
examples: 


*-(PUSHNEW STACK 'A) 
(B A) 

«-(PUSHNEW STACK 'C) 
(C B A) 


(PUSHLIST (datum) <item1) ... (itemN)) 
The specified items are APPENDed rather than CONSed to the front of the cur- 
rent value of (datum). 


(POP <datum)) 
The first element of (datum) is returned. The CDR of the original value of «da- 
tum) is stored as the new value of «datum). Consider the following examples: 


«(POP STACK) 
C 


“STACK 
(B A) 


«(POP STACK) 
A 


«(POP STACK) 
NIL 


(SWAP (datum1) (datum2)) 
The values of (datum1) and <datum2) are assigned to each other. Consider the 


following example: 
<(SETQ X 100) 
100 


«(SETQ Y 200) 
200 
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«(SWAP X Y) 
200 
<-X 
200 
+y 
100 


«CHANGE (datum) <form)) 

The value of (form) is an arbitrary expression that enables you to specify what 
the new value of <datum) should be. The new value of (datum) is the value of 
<form )* where <form )* is constructed from <form) by substituting the value of 
<{datum) for every occurrence of the literal atom DATUM in <form). 


23.10.2 Defining New CLISP Words 


You may define new CLISP words for use by the CHANGETRAN Package by 
placing the property CLISPWORD on the atom representing the word. The 
value of the property has the form 


(CHANGETRAN . <word)) 


_ You must put the property on both the upper- and lower-case versions of the 
word. On the lower-case version of the word, you must place the property 
CHANGEWORD with a function as its value. The function will be applied to a 
single argument, the expression which is the argument to the word. It must re- 
turn an expression that CHANGETRAN can translate into an appropriate ex- 
pression. 

The expression returned from the function should include the literal atom 
DATUM wherever you want to access the current value of the datum that ap- 
pears as the first argument to the word. The form (DATUM*+ (expression) 
must appear only once in the expression. It specifies that an appropriate expres- 
sion for storing into the datum should occur at that point. 

The IRM suggest the following definition for the CHANGEWORD SUB: 


<-(PUTPROP 'sub 
' CHANGEWORD 
'(LAMBDA (form) 
(LIST 'DATUM<— 
(LIST 'DIFFERENCE 
"DATUM 
(CONS 'IPLUS (CDDR FORM) ))))) 
(LAMBDA (FORM) (LIST (QUOTE DATUM«-) (LIST (QUOTE 
DIFFERENCE) (QUOTE DATUM) (CONS (QUOTE IPLUS) (CDDR 
FORM) ) ) ) ) 
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+-(PUTPROP 'SUB 'CLISPWORD '(CHANGETRAN . SUB)) 
(CHANGETRAN . SUB) 


Note that you do not have to define the lower-case version if you do not want 
to! Personally, since INTERLISP generally believes in upper-case syntax, I find 
it difficult to use lower-case words. 


«(SETQ X 100) 
100 


<—(SUB X 25) 
75 


The CHANGETRAN facility allows you to define new languages for inter- 
acting with INTERLISP and with your programs. By defining ‘‘words”’ and their 
translations, you may create different interfaces for different users. 
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INTERLISP provides many utility packages which cannot be included in the 
standard loadup (e.g., the initial SYSOUT file) due to virtual address space lim- 
itations. This is true whether you are running under INTERLISP-10, IN- 
TERLISP/370, or INTERLISP-D. This chapter will survey some of these pack- 
ages and describe some of the functions included therein. Because of the large 
number of packages provided by INTERLISP-10 (and the even larger number 
provided by INTERLISP-D), I can only briefly discuss some of the more salient 
features of many of these packages. In general, additional documentation may 
be found in files on the respective file systems supporting your INTERLISP envi- 
ronment. 

I will discuss only those packages which work on any of the versions of IN- 
TERLISP. Packages specific to a version (such as INTERLISP-10) are described 
in the IRM which you should consult for more information. 


24.1 FILE SYSTEM EXTENSIONS 


Many of the LISP User’s packages provide additional functions that extend the 
capabilities of the file system or the File Package. These packages are discussed 
in the following sections. 


24.1.1 Indexing a File 


SINGLEFILEINDEX is a package for alphabetically indexing the functions 
found in a single file. The function index is placed at the beginning of the source 
file. An index consists of a number of columns whose entries are a file name and 
a byte offset into the file. The number of columns is determined by the length of 
the longest function name and the number of functions within the file. More- 
over, each function is preceded by its function right-justified on a page. 
SINGLEFILEINDEX, when loaded, modifies the execution of LIST- 
FILES1, a worker function called by LISTFILES (see Section 17.3.4). 
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SINGLEFILEINDEX includes the function SINGLEFILEINDEX which 
performs the indexing and printing to the output file. It takes the form 


Function: SINGLEFILEINDEX 
# Arguments: 3 
Arguments: 1) a source file, SRCFILE 


2) a destination file, DSTFILE 
3) a new page flag, NEWPAGEFLG 


Value: The source file name. 


SRCFILE must be a source code file. DSTFILE must be the name of a file or 
NIL. If it has the same value as SRCFILE, then a new version of SRCFILE will 
be created (the normal case). If DSTFILE is NIL, the output will be directed to 
the global variable PRINTER which is usually initialized to the name of the line 
printer for your INTERLISP system. 

NEWPAGEFLG determines whether each function will be printed begin- 
ning on a new page. If NEWPAGEFLG is T, this will be done. It usually has the 
value NIL. 

SINGLEFILEINDEX uses the following variables: 


FILELINELENGTH To determine how to right- _ 
justify function indices and to 
columnate within the file. 


PRINTER A global variable containing the 
name of the psuedo-file 
corresponding to the system 
printer. 


LINESPERPAGE The number of lines per page 
that are normally allowed by the 
printer, so it may determine 
when to insert page breaks for 
nice formatting. The initial 
value is 58. 


The compiled code for SINGLEFILEINDEX resides in the file SINGLE- 
FILEINDEX.COM. 


24.1.2 Indexing Multiple Files 


MULTIFILEINDEX is a package for indexing a set of files which comprise all or 
part of a system. When you have a large number of files comprising a system, the 
listings representing the system aren’t much use because you have no way of 
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finding your way around them. The problem is particularly acute if you are not 
intimately familiar with the structure and implementation details of the system. 
MULTIFILEINDEX can assist you by creating an alphabetized table of con- 
tents of the files with all functions indexed and other data structures (such as 
records, blocks, etc.) appropriately noted. 

MULTIFILEINDEX requires that the COMS of each file to be processed be 
loaded into memory. It uses the function GETDEF to obtain the definition of 
variables from the source file. In many files, there may be several levels of indi- 
rection. For example, if the list of functions contained within the file is supplied 
as the value of a variable, say TESTFNS, with the COMS entry appearing as 
(FNS * TESTFNS), a GETDEF to the COMS entry does not obtain all of the 
required information. MULTIFILEINDEX will perform a GETDEF to obtain 
the value of TESTFNS as well. 

MULTIFILEINDEX contains a single function that is invoked by the user, 
MULTIFILEINDEX. It takes the form | 


Function: MULTIFILEINDEX 
# Arguments: 3 


Arguments: 1) a list of source files, SRCFILES 
2) a destination file, DSTFILE 
3) a new page flag, NEWPAGEFLG 


Value: A list of files processed. 


SRCFILES may either be a list of files (such as that created by FILES?) or 
an atom. If it has the value NIL, MULTIFILEINDEX returns immediately. If it 
has the value T, the value of FILELST is used. If it is an atom, but not NIL or T, 
then FILEFNSLST is applied to its value under the assumption that it is the 
name of a file. 

DSTFILE is the destination file where the output from MULTIFILEINDEX 
will be written. For large numbers of files, the output can be voluminous. If 
DSTFILE has the value NIL, the value of the global variable PRINTER is used 
(it stores the name of the system printing device). 

NEWPAGEELG indicates whether each function in the listing should be 
printed on a page by itself. Giving it the value of T enables this action. 

MULTIFILEINDEX produces an output file that contains 


1. A listing of all the functions in a file with each function being preceded by 
its index number within the file right-justified on the line. 

2. An alphabetized table of contents indicating the name of each IN- 
TERLISP object or entity, the file that it belongs to, and its type. If the 
entity is a function, the information also includes a unique index in the 
listing, its type, and its argument list. 
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In addition, each file that is treated by MULTIFILEINDEX will have its 
name removed from NOTLISTEDFILES. 

Header information will be placed at the top of each page. Each page is 
numbered. Page width is controlled by FILELINELENGTH while page length is 
controlled by LINESPERPAGE. LINESPERPAGE initially has the value 58 as 
described in Section 24.1.1. 

MULTIFILEINDEX formats the columns of its report according to the val- 
ues of four global variables: 


MULTIFILEINDEXCOLS Indicates how the other 
three columns are to be 
interpreted. If it has the 
value FLOATCOLS, which is 
the default, MULTIFILEINDEX 
attempts to arrange the 
columns on the page such 
that the amount of space 
for the type information is 
maximized. This space must 
be at least 45% of 
FILELINELENGTH. 


If it has the value T or 
FOXCOLS, the values. of the 
other variables indicate 
absolute column positions 
on the page. 


If it has the value NIL or 
FIXFLOATCOLS, the columns 
will be floated on the 
page, but will not be any 
smaller than the columns 
defined by the values of. 
the other variables (e.g., 
you may specify minimum 
size columns). 


MULTIFILEINDEXNAMECOL Specifies the position of 
the name column in the 
report. Initially, its 
value is 0. 


MULTIFILEINDEXFILECOL Specifies the position of 
the file name column. 
Initially, its value is 26. 








MULTIFILEINDEXTYPECOL 
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Specifies the position of 
the type information 
column. Initially, its 
value is 41. 


You may control the information that is actually printed to the destination 


file through four variables: 


MULTIFILEINDEXMAPFLG 


MULTIFILEINDEXFILESFLG 


MULTIFILEINDEXFNSMSFLG 


MULTIFILEINDEXVARSMSFLG 


Indicates that you want the 
file index to be printed to 
the destination file. 
Initially, it has the value 
Te 


Indicates that you want the 
files output to the 
destination file. 
Initially, it has the value 
De 


Indicates that you want 
Masterscope information 
produced about each 
function in the destination 
file. Initially, it has the 
value NIL. 


Indicates that all the 
variables used in the files 
will have some information 
about them produced in the 
report. The list of 
variables considered is 
determined by the answer to 
the Masterscope question 
"WHO IS USED BY ANY AND WHO 
IS SET BY ANY''. The 
variable map is sorted by 
variable name independent 
of case. Initially, it has 
the value NIL. 


The latter two variables use the interface to Masterscope included within - 
MULTIFILEINDEX to obtain the necessary information. If either variable has 
the value T, MULTIFILEINDEX assumes that the source file(s) have been ana- 


lyzed by Masterscope. 
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The compiled code for MULTIFILEINDEX resides in the file MULTI- 
FILEINDEX.COM. 


24.1.3 Implementing the ALL File Package Type 


The ALL File Package type allows you to intermix definitions of various types for 
a given atom in a file. This capability is useful if you must produce listings since 
all. the information is collected in a single location. The file defines both a File 
Package command and a File Package type. 

The File Package command has the form 


(ALL (filepackagetypes) <specification1) ... 
{specificationN) ) 


The field <filepackagetypes) is a list of the file package types that may be 
stored in the list. f 
The fields <specification1) ... <specificationN) are lists consisting of an 
atom name and one or more types for which information is to be dumped. 
Consider the following example: 


(ALL 
(COMMENTS FNS VARS MACROS RECORDS) 
(GET.TREE FNS VARS) 
(GET.FOREST VARS 
(GET.BRANCH MACROS) ) 


which dumps the function definition and the value of GET.TREE, the value of 
GET.FOREST, and the macro definition of GET.BRANCH. 

The special form (ALL * <file> ALL) is also recognized and handled as de- 
scribed in Section 17.2.20. 

In the specifications, the type may also be a list of the form (PROPS ¢prop- 
ertyl) ... <propertyN)) which means to store the specified properties for that 
atom in the file. . 

When you store a definition for an atom A1 of type T1 on a file, the File 
Package looks for a command in which to put it (in the source file). 

When an ALL command is encountered, the File Package uses the following 
procedure: 


1. If T1 is not in the type list for the ALL command, then the definition will 
not be included in the command (e.g., ALL “‘overrides” the normal oper- 
ation). 

2. If Al already exists in the command, then T1 will be inserted while at- 
tempting to maintain the order specified in the type list. 

3. Otherwise, an entry of the form (A1 T1) is inserted in the command list. 
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4. If the File Package cannot put the definition into an existing command, 
it creates a new command. 

5. Ifthe type is a member of the list ALL-TYPES, then the File Package will 
create a command of the form (ALL {all-types) (A1 T1)). 


The variable ALL-TYPES is a list of all the File Package types that will be 
intercepted by an ALL command. It is also the list of types that will be inserted 
into a newly created ALL File Package command as described above. Its initial 
value is 


(COMMENTS FNS MACROS VARS LISPXMACROS USERMACROS) 


but you may modify it to suit your own requirements. 


24.1.4 Editing a File’s History 


EDITHIST provides extensions to the File Package that allow you to perma- 
nently preserve the history of new versions of files. It records a ‘‘who-edited-last”’ 
comment within the file for each function. 

Every time a file is remade, EDITHIST will cause a new entry to be recorded 
in the file’s edit history. The entry has the form 


(<date) <author) <file>) (<changes)) (<comments)) ) 


where 

{date) is the value of (DATE) when the file 
was remade 

{author) is the value of (OR INITIALS USERID) 

«file> is the full file name of the output 

«changes ) is the same list of changed items 
that appears on the FILEDATES 
property 

<comments) is acquired (optionally) by ASKUSER 


during the execution of MAKEFILE. 


When EDITHIST is loaded (usually during evaluation of INIT.LSP), it as- 
signs default values to certain control parameters: ASKEDITHIST and LIMI- 


TEDITHIST. These variables are interpreted as follows: 


ASKEDITHIST Controls the invocation of ASKUSER 
when a file is remade. It takes one 
of the following values: 
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NIL Don't ask the user for 
comments and do not 
extend the 
edithistory. 

NOCOMMENT Don't ask the user for 


comments, but do 
extend the edithistory 
with no comments 
field. 


COMMENT Ask the user for 
comments and extend 
the edithistory with a 
comments field. 


T Add an edithistory to 
any file that does not 
currently have it; ask 
the user for comments 
and extend the 
edithistory. This is 
the default value. 


LIMITEDITHIST Controls the pruning of the 
edithistory. It takes the form 


(#softlimit . #hardlimit) 


with a default value of (10 . 30). 
#softlimit specifies the number of 
recent entries to remain inviolable. 
#hardlimit specifies the threshold 
when pruning will be invoked. 


The edit history may grow quite large if the file is edited repeatedly during 
the development and debugging of a program. When a threshold is reached, the 
edit history will be pruned to reduce its size while preserving as much informa- 
tion as possible. EDITHIST uses the following procedure to prune the edit his- 


tory: 


1. Preserve the first N entries, where N is given by #softlimit. 

2. Among the remaining entries, merge entries with the same author and no 
comments. ; 

3. If the number of entries remains above the threshold, merge entries hav- 
ing no comments, but different authors (i.e., ignore the authors). 
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4. If still above the threshold, merge N of the oldest entries into a single 
entry that brings the number of entries below the threshold. 


When entries are merged, the (date), (author), and (file) fields are 
CONSed together in the result. The (changes) list in the merged entry is the 
union of the individual changes in the contributing entries. The (comments) 
field in the merged entry is the concatenation of all the comments of the contrib- 
uting entries. 

At some point, you must manually edit the edithistory to remove the oldest 
information. EDITHIST will not discard information from entries, but merely 
create successive mergers that become unmanageable. 

EDITHIST also defines additional options for MAKEFILE’s OPTIONS 
field which provide temporary overrides: 


ASK Temporarily resets ASKEDITHIST to T so you 

COMMENT will be asked for a comment this one time 
only. 

NOASK Temporarily resets ASKEDITHIST to 

NOCOMMENT NOCOMMENT so you will not be asked for 


comments this one time only. 


EDITHIST maintains the edithistory for each file in ALIST format keyed by 
the file name. The root of the list is EDITHISTALIST. You may examine or 
modify an edithistory using either (EDITDEF filename) ‘EDITHIST) or 
(SHOWDEF (filename) ‘EDITHIST). 

An edithistory is declared DONTCOPY so it will not be included in com- 
piled files. If the compiled file is remade, the edithistory is recovered from the 
source file. 

You may include a File Package command (EDITHIST (filenames )) in the 
file’s command list. If multiple file names are present (due to merged files), only 
the first will be subsequently updated. 


24.1.5 Making Files Permanently Open 


PERMSTATUS is intended to be used with the WHENCLOSE Package (see 
Section 16.5.3) to preserve a file’s open status after an environment is restored 
from a SYSOUT file. The effect is to make the file “permanently” open. 

You may achieve this effect (after loading the file PERMSTATUS.COM) by 


executing the expression 
(WHENCLOSE (filename) 'STATUS 'PERMSTATUS) 


after the file has been opened. Information will be saved about the file that per- 
mits its restoration after reloading a SYSOUT file. This information includes its 
access mode, file pointer value, and byte size. 
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The permanence of a file is not guaranteed. You may delete or rename the 
file or change its contents by means external to the INTERLISP environment. If 
a file cannot be found or restored during the loading of a sysout, a warning mes- 
sage will be printed. 

Permanent files will be closed by CLOSEF or CLOSEALL or due to edosive 
on end-of-file errors unless the appropriate attributes are specified via the 
WHENCLOSE Package. 


24.2 EXTENSIONS TO MASTERSCOPE 


Two LISP User’s Packages extend the capabilities provided by Masterscope (see 
Chapter 26). 


24.2.1 Dumping Masterscope’s Knowledge 


Masterscope builds a database describing one or more files which it has ana- 
lyzed. The TELL Package allows you to obtain a complete dump of all of Mas- 
terscope’s knowledge about a selected set of atoms, functions, or Masterscope 
relations. TELL defines a number of functions that allow you to extract varying 
amounts of information from the Masterscope database. 

TELLABOUT allows you to obtain information about a list of atoms de- 
scribed in the Masterscope database. It takes the form 


Function: TELLABOUT 
# Arguments: 4 


Arguments: 1) a subject list, SUBJECTS 
2) a list of related atoms, UNIVERSE 
3) a question list, OMITQUESTIONS 
4) a destination file, DUMPFILE 


Value: The destination file name. 


SUBJECTS is a list of atoms about which information is desired. UNI- 
VERSE is a list of atoms which are related to the atoms appearing on SUB- 
JECTS. Whenever one of these atoms is detected in a Masterscope relation, it 
will be printed. 

OMITQUESTIONS is a list of question numbers (see below) for those ques- 
tions which are not to be asked of the Masterscope database. 

DUMPFILE is the destination file where the output from Masterscope will 
be written. 

For each atom on SUBJECTS, TELL prints an entry that contains the an- 
swers to every question asked by ENUMERATEQUESTIONS of the Master- 
scope database except those identified by OMITQUESTIONS. The atom is sub- 
stituted for the * in the questions described below. Members of UNIVERSE will 
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be substituted for WHO or WHOM in the questions. If the answer is true, then 
an entry is printed. 


At the end of the file, TELLABOUT displays all of the questions asked and 
the value of UNIVERSE. 


TELL assumes that Masterscope has already analyzed the functions which 
are the source of the information. 


24.2.2 Enumerating the Masterscope Questions 


ENUMERATEQUESTIONS prints a list of questions at your terminal that ex- 
haustively describes all of the simple relations among objects that are indexed by 
Masterscope. Each questions is prefixed by an integer identifying the question 
which may be used in TELLABOUT. It takes the form 


Function: ENUMERATEQUESTIONS 

# Arguments: 0 

Arguments: N/A 

Value: NIL, but the list of questions is a side 
effect. 


The list of questions printed by ENUMERATEQUESTIONS at your termi- 
nal is as follows: 


. Whom does * bind? 

. Whom does * bind locally? 

. Whom does * bind as an argument? 
. Whom does * call? 

. Whom does * use? 

Whom does * use freely? 

. Whom does * use locally? 

. Whom does * use globally? 

. Whom does * use as a record? 

. Whom does * use as a field? 

. Whom does * use as a property? 

. Whom does * use as a CLISP i.s.operator? 
. Whom does * set? 

. Whom does * set freely? 

. Whom does * set locally? 

. Whom does * set globally? 

. Whom does * smash? 
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Whom does * smash freely? 
Whom does * smash locally? 
Whom does * smash globally? 
Whom does * test? 

Whom does * test freely? 
Whom does * test locally? 


24. Whom does * test globally? 


Whom does * reference? 


26. Whom does * reference freely? 


- Whom does * reference locally? 


Whom does * reference globally? 
Who binds *? 


. Who binds * locally? 


Who binds * as an argument? 


- Who calls *? 
- Who uses *? 


34. Who uses * freely? 


. Who uses * locally? 


36. Who uses * globally? 


. Who uses * as a record? 


38. Who uses * as a field? 


. Who uses * as a property? 


Who uses * as a CLISP I.S.operator? 


- Who sets *? 


Who sets * freely? 


. Who sets * locally? 
. Who sets * globally? 
. Who smashes *? 


Who smashes * freely? 


. Who smashes * locally? 


Who smashes * globally? 


. Who tests *? 
. Who tests * freely? 


Who tests * locally? 

Who tests * globally? 

Who references *? 

Who references * freely? 
Who references * locally? 
Who references * globally? 
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24.2.3 Finding Out about Everything 


You may find out about everything that Masterscope has seen by executing 
EVERYONE, which takes the form 


Function: EVERYONE 

# Arguments: 0 

Arguments: N/A 

Value: A list of answers to the questions noted 
below. 


EVERYONE returns a list which describes everything Masterscope knows 
about objects it has seen (i.e., that have been analyzed) except for system func- 
tions and I.S.OPRS. In particular, EVERYONE will answer the following ques- 
tions: 


. Who is known? 

- Who is used? 

. Who is used as a property? 
- Who is used as a field? 

- Who is used as a record? 


akh WwW nN = 


Dumping the Results of EVERYONE 
You may dump the results of executing EVERYONE to a file by executing 
TELLABOUTEVERYONE, which takes the form 


Function: TELLABOUTEVERYONE 
# Arguments: 2 
Arguments: 1) a list of questions to be omitted, 
OMITQUESTIONS 
2) a dump file name, DUMPFILE 
Value: The value returned by EVERYONE. 


TELLABOUTEVERYONE calls TELLABOUT with the argument list: 
(EVERYONE() EVERYONE() DUMPFILE). 

You may produce an exhaustive but not overly redundant set of information 
about functions in the Masterscope database using BASISTELLABOUT, which 


takes the form 


Function: BASISTELLABOUT 
# Arguments: 1 
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Arguments: 1) a dump file name, DUMPFILE 


Value: The dump file name. 


BASISTELLABOUT calls TELLABOUTEVERYONE with the argument 
list (REASONABLEOMISSIONS DUMPFILE). 

REASONABLEOMISSIONS is a variable whose value is a list of the num- 
bers of the questions whose answers are supersets of the answers to simpler ques- 
tions. The only information that is not dumped by omission these questions ap- 
pears to be information about I.S.OPRS. 

These functions are stored in the file (LISPUSERS)TELL.COM. 


24.2.4 Automatic Masterscope Database Creation 


Normally, you must manually create a Masterscope database by explicitly di- 
recting Masterscope to analyze a set of functions and index the information in 
the database. The functions stored in the DATABASEFNS package attempt to 
make this process automatic. 

When DATABASEFENS is loaded, it modifies MAKEFILE, LOAD, and 
LOADFROM (see Chapter 17) to automatically update an existing Masterscope 
database. 

When a file is made or loaded via MAKEFILE, LOAD, or LOADFROM, 
the Masterscope database will be automatically maintained if the atom corre- 
sponding to the file name has the property DATABASE with the value YES. 
Whenever a file is dumped via MAKEFILE, Masterscope will analyze any the 
functions in the file to determine if any have been modified or if new functions 
have been added to the file. A new database whose name is <filename).DATA- 
BASE will be written with information concerning the new or changed functions. 

Whenever a file is loaded via LOAD or LOADFROM, the corresponding 
(filename). DATABASE file will also be loaded. 

The database will be neither dumped nor loaded if the value of the property 
DATABASE is NO. If the file is loaded with LDFLG having the value SYS- 
LOAD, then the value of the DATABASE property will be assumed to be NO. 

If the value of the DATABASE property is neither YES nor NO (a good 
value is ?), then you will be asked whether or not you want the Masterscope 
database automatically maintained at the first execution of MAKEFILE, 
LOAD, or LOADFROM for the indicated file. Your answer is stored as the 
value of the DATABASE property so that you will not be repeatedly asked the 
question. This feature is controlled by two global variables: 


SAVEDBFLG A value of YES or NO will be stored 
instead of asking the question if the 
value of the DATABASE property is 
neither YES or NO depending on 
whether its value is YES or NO. Its 
value is initially ASK. 
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LOADDBFLG A value of YES or NO will be stored 
instead of asking the question if the 
value of the DATABASE property is 
neither YES or NO depending on 
whether its value is YES or NO. Its 
value is initially ASK. 


You will be queried if the value of either of these variables is ASK. 
Dumping and Restoring MSDATABASE 


You may explicitly dump and restore Masterscope databases using SAVEDB 
and LOADDB, which take the form 


Function: SAVEDB 
LOADDB 
# Arguments: 1 
Arguments: 1) a file name, FILE 
Value: The file name. 


SAVEDB dumps a database for FILE and then sets the DATABASE prop- 
erty of the atom corresponding to the file name to YES. Thus, database mainte- 
nance for that file will be automatically performed on each subsequent MAKE- 
FILE. The file that is created has the name (filename). DATABASE. 

LOADDB loads the database file having the name <filename).DATA- 
BASE, if one exists, associated with FILE. After the database is loaded, 
LOADDB sets the value of the property DATABASE of the atom corresponding 
to the file name to YES to make database maintenance automatic thereafter. 

You may not load a database file with the standard INTERLISP loading 
functions because of its special format. LOADDB is the only way to access a 
database file. 

These functions are stored in the file «LISPUSERS) DATABASEFNS- 
-COM. 


24.3 THE DECL PACKAGE 


Several conventional languages allow you to restrict the scope of arguments to 
functions by specifying the datatypes of variables that are passed as arguments 
to those functions. Normally, this takes the form of declaring the variable name 
and typing in the argument list associated with the function (or procedure) defi- 
nition. Examples of such languages include PASCAL and ADA. 

INTERLISP normally allows you to pass any type of expression or variable 
to a function. It is incumbent upon the called function to determine the type of 
the argument and whether or not the type is a valid one for the function to oper- 
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ate upon. Thus, in many functions, if the user is a careful programmer, you will 
see a COND statement checking the types of the arguments. 

The DECL Package provides a mechanism for introducing lexical scoping in 
INTERLISP functions. Lexical scoping constrains the behavior of INTERLISP 
functions such that the type of arguments passed to the function is checked when 
the function is called. To do so, the DECL Package modifies the actions of both 
the INTERLISP interpreter and the compiler. 

Type declarations on arguments can make the function more readable since 
they indicate more clearly (if mnemonic names are chosen for functions) what 
the function is intended to do. They also facilitate debugging of functions since 
they assist in localizing errors that are the result of type incompatibilities be- 
tween the arguments passed and those expected by the function. Type declara- 
tions will be recognized by Masterscope when the DECL Package is loaded. 


24.4 TRANSOR: A LISP TRANSLATOR 


As explained in Chapter 1, there are two major dialects of LISP. The other dia- 
lect, MACLISP, has a number of subdialects as described in Section 1.2. Differ- 
ences between INTERLISP and these dialects are noted therein. TRANSOR is a 
LISP-to-LISP translator that allows you to effectively translate LISP programs 
in one dialect into another (i.e., the translation may be to or from INTERLISP). 

TRANSOR is driven by a set of transformation specifications which de- 
scribe the differences between the two dialects. The differences are expressed as 
INTERLISP Editor commands which will convert the input dialect form into an 
output dialect form. When TRANSOR is loaded along with the transformation 
file, it will read the input file and apply the edit transformations to all expres- 
sions within the file. It produces an output which should be suitable for loading 
on the target LISP system. In addition, TRANSOR will produce a set of trans- 
formation notes that describe the major changes made to the input source code 
to produce the output file. It also notes any additional changes that require fur- 
ther attention from the user. 

TRANSOR may be thought of as a driver for a massive editing task. While 
the primary usage is to translate from one LISP dialect to another, proper speci- 
fication of the edit transformations may allow you to translate a large percentage 
of a source file in another language (such as C) to INTERLISP or vice versa. 


24.5 OTHER LISP USER’S PACKAGES 


There are numerous other LISP User’s Packages that are available under IN- 
TERLISP-10 which work only with INTERLISP-10. There are also many pack- 
ages available with INTERLISP-D which will be described in Volume 2. 

The following sections provide just a brief glimpse of some of the other pack- 
ages available for INTERLISP-10. You may find documentation on these pack- 
ages in the LISPUSERS directory on a DECSystem-10 computer system. 
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24.5.1 The Pattern Match Compiler 


The Pattern Match Compiler is a package that provides additional flexibility in 
specifying patterns to be matched within CLISP statements. 

In general, you want to answer the question: Does the expression X look like 
the pattern P? The Pattern Match Compiler provides a syntax that allows you to 
specify patterns and the rules for matching them. 


24.5.2 The Hash File Package 


The Hash File Package allows you to effectively extend the memory of the IN- 
TERLISP-10 system by permitting information associated with atoms or strings 
to be stored on a file rather than in memory. The information is retrieved as it is 
needed by the program. To make the retrieval efficient, the Hash File Package 
makes use of the INTERLISP-10 page mapping facility to access the informa- 
tion stored in the file(s). 


24.5.3 EDITA: The Array Editor 


EDITA is an Array Editor. However, its most frequent use is in editing compiled 
functions which are represented as arrays in INTERLISP-10. While EDITA is 
also available on INTERLISP-D, capabilties pertaining to the editing of com- 
piled code will only work for INTERLISP-10. 

In general, you invoke EDITA to edit a function. It then accepts commands 
similar to the DECSystem-10 DDT (Dynamic Debugging Tool). The commands 
allow you to open registers (i.e., memory locations), examine symbol tables, 
change the contents of memory locations, and search for specific values. 


24.5.4 CJSYS: Access to the Operating System 


CJSYS is a package running under INTERLISP-10 that allows you direct access 
to the underlying operating system. Operating system calls in TENEX and 
TOPS-20 are call JSYS (Jump to SYStem) traps; hence the name of the package. 


24.5.5 EXEC: A TENEX Executive in INTERLISP 


EXEC is a package that defines additional Programmer's Assistant commands 
that provide you with some of the capabilities of the TENEX EXEC. These capa- 
bilities provide you with access to certain operating system features while not 
requiring knowledge about the specific interfaces (i.e., no need to use CJSYS). It 
also defines functions that provide the same capabilities so that you may exercise 
them from within your programs. 
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24.5.6 The NET Package 


The NET Package provides functions for establishing ARPANET connections 
from INTERLISP-10 jobs. You may open, close, and check connections with 
other computers in the ARPANET (provided you have an account on them). 


24.5.7 FTP: The File Transfer Package | 


FTP is a package that allows you to transfer files between hosts on the AR- 
PANET. When FTP is loaded, you may access files at other ARPANET hosts 
using the basic file system commands INFILE, OUTFILE, and OPENFILE, 
and you may read and write those files as if they were resident at your local host. 


,. 








25 





The Programmer’s 
Assistant 


The Programmer’s Assistant is a subsystem that interacts with you to assist in 
creating and running programs. You may think of it as an aide who looks over 
your shoulder at what you are doing. Normally, expressions that you type in are 
executed without any interference by the Programmer’s Assistant. However, it 
does recognize a set of commands that cause it to do things for you. Among the 
functions that it may perform are 


1. Remembering and repeating a sequence of commands that you have pre- 
viously entered. 

2. Undoing the effects of commands you have recently executed. 

3. Analyzing erroneous input and presenting you with a diagnosis of what 
went wrong. 


The Programmer’s Assistant is dispersed throughout INTERLISP. I have 
chosen to discuss it in two chapters in order to enhance the clarity of presenta- 
tion. This chapter concentrates upon the main features and concepts that un- 
derly the Programmer’s Assistant. Chapter 28 discusses the History Package 
which supports the auditing and undoing of expressions. 


25.1 THE CONCEPT OF UNDOING 


Undoing means to reverse the effects of an expression that you have previously 
typed in and INTERLISP has executed. Undoing requires that each expression 
that might be undone have information stored on a history list to enable reversal 
of its side effects. The Assistant has no way of knowing when it is about to per- 
form a destructive operation. To constantly check for such occurrences would 
seriously degrade the efficiency of the system. Rather, the Assistant merely 
“watches” the execution of expressions. HISTORYSAVE (see Section 28.6.1) 
automatically saves undoable changes on the history list. Undoing involves read- 
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ing the history list to access the information necessary to perform the inverse 
operations. 

As we said previously, the Assistant is relatively passive until you instruct it 
to do something. Only then does it check to see if the necessary information is 
available on the history list. If the user explicitly identifies the event and nothing 
has been saved, the Assistant prints the message ‘NOTHING SAVED”. Other- 
wise, it searches for the last undoable event (ignoring events already undone as 
well as other UNDO operations) and undoes it. 

The primary question is: How does the system know what is undoable and 
what is not? Underlying this question is the problem of efficiency. The ability to 
undo every operation would rapidly consume storage to save the information 
necessary to perform the inverse operation. Moreover, only a few system func- 
tions are really destructive. Thus, these are the only ones we need to know some- 
thing about in order to undo them. Perversely, however, these are the functions 
that are executed most often, which leads us back to the problem of storage 
consumption. 

The Assistant has solved this problem by forcing two constraints on undo- 
ing: 


1. Each function which may be undone must save the appropriate informa- 
tion necessary to undo its effects on the history list. 


2. For each primitive destructive function, there are actually two implemen- 
tations—one that is undoable and one that is not. The undoable function 
saves the necessary information on the history list when it is executed. 
You decide what may be undone by your choice of the implementation of 
the destructive function. 


Most of the INTERLISP subsystems use the undoable versions of the primi- 
tive destructive functions. You may also use these functions if you want func- 
tions that you execute to be undoable as well. 

The Assistant makes an assumption that all expressions that are typed into 
LISPX should be undoable because errors are most likely to occur during inter- 
active dialogue. Thus, the Assistant substitutes the corresponding undoable 
function for each destructive operation that it encounters on type-in. This as- 
sumption is based on the fact that most expressions that are typed in rarely in- 
volve iterations or lengthy operations directly (when was the last time that you 
typed a PROG statement upon receiving a prompt?). 

LISPX (see Section 25.2) scans all input statements before executing them. 
It substitutes undoable versions of the primitive destructive functions for all reg- 
ular versions detected in the input expression. You may wish to make other func- 
tions undoable by performing your own substitutions. You may do so by defining 
LISPXUSEREN (see Section 25.3) to be a function that processes your input 
expressions according to your own requirements. 

Undoing may be fraught with danger. Certain sequences of operations must 
be performed in exactly the reverse order for the system to revert to its proper 
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former state. These include functions that make substantial use of /RPLACA 
and /RPLACD or that perform several successive operations on a single list. 
Good programming practice requires that you undo these types of functions in 
the reverse order of their execution. 


25.2 LISPX: TYPE-IN EVALUATION 


The Assistant uses LISPX (for LISP eXecutive) to obtain an expression for eval- 
uation. INTERLISP reads the first expression typed into the system after the 
prompt character. It calls LISPX with this expression assigned to the variable 
LISPXX. LISPX takes the form 


Function: LISPX 
# Arguments: 5 
Arguments: 1) the initial expression, LISPXX 
2) the value of the prompt character, 
LISPXID 


3) lispx macros, LISPXXMACROS 

4) a user processing function, 
LISPXXUSERFN 

5) a flag, LISPXFLAG 


Value: The value of the expression as computed. 


If the value of LISPXXUSEREN is non-NIL, the input expression will be 
passed to it for processing. If so, you do not need to define a value for LISPX- 
USEREN. 

You may invoke LISPX from within your program if you wish certain inputs 
to be undoable. LISPXID allows you to define your own prompt character to 
signify that input is being directed to your own function rather than IN- 
TERLISP. 

LISPX processes the input as follows: 


1. If the value of LISPXX is not a list, LISPX calls READLINE to read the 
remaining expressions up to a break character or a carriage return. The 
value of LISPXX is concatenated with the value of READLINE and the 
result is stored on the history list. LISPX then decides what to do with the 
input it has received. The possibilities include 


a. It is a history command to be executed. LISPX invokes HIS- 
TORYSAVE, executes the command, and returns the value of 
HISTORYSAVE. 

b. It is a LISPXMACRO (see Section 25.2.1). 

. It is to be processed by a LISPXUSEREN (see Section 25.3). 


d. It calls EVAL or APPLY depending upon the input form. 


io) 
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- 


If LISPXX is a list whose CAR is LAMBDA or NLAMBDA, LISPX in- 
vokes LISPXREAD to obtain the arguments which include the argument 
list and all expressions composing the body of the function. A list is indi- 
cated by an opening (. 

If LISPXX has the value ) or ], READLINE returns (NIL) instead of 
NIL. This permits you to call a function with no arguments as in 


Ww 
. 


CLEANUP] 


which then uses FILESLST to do its work. Note that this distinguishes 
the execution of the function CLEANUP from the variable CLEANUP 
which would have been typed as 


<-CLEANUP< CR) 


4. If the expression consists of a list preceded by other characters than 
spaces and terminated by a ) or a ], LISPX treats the expression as being 
in APPLY format and proceeds accordingly. 


<-EDITF(REDRAW.MAP) 
which invokes the Editor on the function REDRAW.MAP. 


LISPX saves the inputs for all but the history commands on a history list 
before executing. Thus, even if the operation is aborted, you may redo it, fix it, 
etc. 

If the input is an EVAL or APPLY form or a form without parentheses (e.g., 
a CLISP statement), the function name will be looked up in LISPXFNS. If you 
want a different function called than you typed in, place an entry of the form 
(<fn1) . <fn2)) on LISPXENS which will cause LISPX to invoke <fn2) whenever 
it detects <fn1) in a form. 

For history commands, LISPX merely unreads the information from the his- 
tory list and exits. However, if your program calls LISPX, history commands will 
not work unless your program obtains input via LISPXREAD. Moreover, your 
program must save the inputs that it reads on the history list in the approved 
format. 

LISPX will perform spelling correction using LISPXCOMS as its spelling 
list. LISPXCOMS is a list of commands recognized by LISPX. Spelling correc- 
tion is applied whenever LISPX receives an atom which is unbound or a function 
which is undefined. 


25.2.1 A Definition for LISPX 
We might define LISPX as follows: 





a a a i te ta 


a re i cl 


————eeeeeeeeereree ree ee rea ae 
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(DEFINEQ 
(lispx (lispxx lispxid lispxxmacros lispxxuserfn) 
x 


If the caller provides no special macros, 
use the standard ones defined by the 
Assistant. 


(AND 
(NULL lispxxmacros) 
(SETQ lispxxmacros LISPXMACROS) ) 
x 
If the caller provides no user function, 
or LISPXUSERFN has the value NIL, use the 
standard LISPXUSERFN. 
) 
(OR 
lispxxuserfn 
(NULL LISPXUSERFN) 
(SETQQ lispxxuserfn LISPXUSERFN) ) 
(PROG (lispxop lispxlistflg lispxline lispxhist 
lispxvalue lispxtemp lispxoptmp) 
(COND 
((NULL lispxx) 
(* 
A spurious right bracket or 
parenthesis was detected. 
Print NIL and try again. 
) 
(RETURN 
(AND 
(NOT silence) 
(PRINT NIL T)))) 
((NLISTP lispxx) 
(SETQ lispxline 
(READLINE NIL T)))) 
top 
(COND 
((LISTP lispxx) 
(* 
Break out the operator and 
its arguments. LISPXOP is 
always the name of the 
history command and 
LISPXLINE is its arguments. 
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(SETQ lispxop (CAR lispxx) ) 

(SETQ lispxline (CDR lispxx) ) 

(SETQ lispxlistflg T)) ~ 
((NOT (LITATOM lispxx) ) 

(* 


If it is not a litatom, 
then it is not a command. 
It could be an error in 
typing or a number. 
(GO notcommand) 
(T 
(SETQ lispxop lispxx))) 
select ; 
(SELECTQ lispxop 
((RETRY REDO FIX USE ...) 
(GO redocommand) ) 
(NAME 
(COND 
((NULL lispxline) 
(* 
NAME may also be 
the name of a 
variable defined 
by the user, so 
try not to 
confuse the two. 


) 
(SETQ lispxx 'E) 
(SETQ lispxline (LIST 
'NAME) ) 
(GO execute.command) ) ) 
(GO redocommand) ) 
(UNDO 
(AND 
(SETQ lispxhist 
(HISTORYSAVE 
LISPXHISTORY 
lispxid 
NIL 
"UNDO 
lispxline) ) 
(RPLACA lispxhist 
(UNDOLISPX 
lispxline) ) ) ) 
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(? 
(PRIN1 "Commands are:" T) 
(PRINT LISPXCOMS T)) 
((RETRY: FORGET ??) 
(* 
If REREADFLG is ABORT, then 
do a CTRL-B via program 
call. 


(AND 
(EQ REREADFLG 'ABORT) 
(ERRORB) ) 
(COND 
((EQ lispxop 'RETRY:) 
(* 
After the RETRY comes 
the command with 
arguments to be 
retried. 
) 
(SETQ lispxx (CAR 
lispxline) ) 
(SETQ lispxline (CDR 
lispxline) ) 
(GO top) )) 
((EQ lispxop 'FORGET) 
(lispx-forget) 
(PRINT 'FORGOTTEN T)) 
((EQ lispxop '??) 
(lispx-??)))) 
(GO notcommand) ) 
(RETURN '?) 
notcommand 
(* 
Determine if LISPXOP is a lispxmacro 
either predefined by INTERLISP or 
specified by the user in this call to 
LISPX. 


(SETQ lispxoptmp 
(ASSOC lispxop 
(OR lispxxmacros 
(CAR (QUOTE 
LISPXMACROS) ) ) ) ) 


(COND 
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(lispxoptmp 
(AND 
lispxlistflg 
(SETQ lispxline NIL)) 
(GO execute.command) ) 
((MEMBER lispxop LISPXCOMS) 
(* | 
At this point, LISPXOP is 
neither a built-in command 
nor a macro. However, the 
user may have put it on 
LISPXCOMS in order to 
process it by LISPXUSERFN. 
) 
(AND 
lispxlistflg 
(SETQ lispxline NIL) ) 
(GO execute.command) ) 
((SETQ lispxoptmp 
(ASSOC lispxop 
lispxhistorymacros) ) 
(* 
If the command is actually 
a macro, find its 
definition and redo it. 
) 
(GO redocommand) ) 
(lispxlistflg 
(* 


The input is a list. 


) 
(COND 
((EQ (CAR lispxx) 'LAMBDA) 
| (* 


A function 
definition! 


) 
(SETQ lispxline 
(LIST 
(LISPXREAD 
T)))) 
(T 
(AND 
(LITATOM (CAR lispxx) ) 
(SETQ lispxop (CAR 
lispxx) ) 
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(SETQ lispxline (CDR 
lispxx) ) 
(GO select) ))) 
(GO execute.command) ) 
((NULL lispxline) 
( AND 
(LITATOM lispxx) 
(COND 
((NEQ (CAR lispxx) 'NOBIND) 
(ADDSPELL lispxx 3)) 
((NEQ (EVALV lispxx) 
'"NOBIND) ) 
((SETQ lispxop 
(FIXSPELL lispxx 
70 
LISPXCOMS 
NIL 


T)) 
(COND 
((LISTP lispxop) 
(SETQ lispxline 
(LIST 
(CDR 
lispxop) ) ) 
(SETQ lispxop 
(CAR 
lispxop) ) )) 
(SETQ lispxx lispxop) 
(GO select) ))) 
(GO execute.command) ) ) ) ) 
execute.command 
(RETURN (LISPXDO-IT) ) 
redocommand 
(LISPXREDOCOMMAND ) 
(RETURN '?))) 


)) 


25.2.2 LISPX Macros 


You may define your own LISPX commands and place them on a list which is 
the value of LISPXMACROS. LISPXMACROS is a list of elements of the form 


(<command) <definition)) 


Whenever one of the <command)s is the CAR of an expression read by 
LISPX, LISPXLINE will be bound to the remainder of the input. The input 
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event is recorded on the history list, and < definition) is evaluated. Its value will 
be stored as the value of the event. 
An alternative form may appear as 


(<command) NIL <definition)) 
which means do not store the event on the history list. 


Initial Definition of LISPXMACROS 
LISPXMACROS is initially defined as 


((NDIR ) 
(DODIR LISPXLINE '(PP COLUMNS 17) '* 0)) 
(DEL 
(DODIR LISPXLINE 'DELETE " " 'L)) 
(CONN 
(CNDIR (CAR LISPXLINE) 
(AND 
(LISTP (CDR LISPXLINE) ) 
(PROG1 
(CADR LISPXLINE) 
‘(RPLACA (CDR 
LISPXLINE) ))))) 
(REMEMBER 
(REMEMBER LISPXLINE) ) 
(REMEMBER : 
(PROGL 
(RESETVARS (FILEPKGFLG) 
(RETURN 
(EVAL (LISPX/ (CAR LISPXLINE) 
LISPXID) ) ) 
(MARKASCHANGED (CAR LISPXLINE) 
'EXPRESSIONS) ) ) 
(OK 
(RETFROM 
(OR (STKPOS 'USEREXEC) 'LISPX) 
T T)) 
(AFTER 
(LISPXSTATE (CAR LISPXLINE) 'AFTER) ) 
(BEFORE 
(LISPXSTATE (CAR LISPXLINE) 'BEFORE) ) 
(RETRIEVE 
(PROG (X REREADFLG) 
(SETQ X (GETP (CAR LISPXLINE) '*HISTORY*) ) 
(COND 
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((NULL xX) 
(ERROR (CAR LISPXLINE) "2" T))) 
(MAPC (CDDR X) 
(FUNCTION 
(LAMBDA (X) 
ee LISPXHISTORY 
X 
(RETURN (CAR LISPXLINE)))) 
(SHH 
NIL 
(COND 
((OR 
(CDR (LISTP LISPXLINE) ) 
(AND 
(MEMBER (LASTC T) '(%) %])) 
(LITATOM (CAR LISPXLINE)) )) 
(APPLY (CAR LISPXLINE) 
(COND 
( (AND 
(LISTP (CADR LISPXLINE) ) 
(NULL (CDDR LISPXLINE) )) 
(CADR LISPXLINE) ) 


(CDR LISPXLINE) ) ) ) ) 
(T 
(EVAL 
(COND 

(LISPXLINE 
(CAR LISPXLINE) 

(T 'SHH)))))) 

(DIR 
(DODIR LISPXLINE) ) ) 


25.2.3 User Processing of Input 


You may intercept the processing of input from the terminal by setting LISPX- 
USEREN to T. You must also define LISPXUSERFN with the definition of the 
function that will process the input. 

When LISPXUSEREN is T, its function definition will be applied to all in- 
puts that are not recognized as Programmer Assistant commands or that appear 
on LISPXMACROS. LISXPUSEREN should attempt to do some recognition of 
the input. The input will already be recorded as an event on the history list. 
Thus, LISPXUSEREN should set LISPXVALUE to the value for the event and 
return T. LISPXVALUE will be stored as the value of the event and will be 
printed at your terminal. 
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If LISPXUSEREFN returns NIL, then EVAL or APPLY is called in the usual 
way as appropriate to the input. 

LISPXUSEREN is usually used to enhance user executives (see Section 
25.3). LISPXUSERFN may be used, when appropriately defined, to process 
natural language input entered by a user at type-in. 

The function definition for LISPXUSEREN is a function of two arguments: 
X and LINE. X is the first expression typed in, and LINE is the remainder of the 
input line as read by READLINE (see Section 14.2.4). A general definition for a 
LISPXUSEREN might appears as follows: 


(DEFINEQ 
(lispxuserfn (x line) 
(PROG (command) 
(COND 
((AND (NULL line) (LISTP x)) 
(SETQ command (recognize (CAR x))) 
(SETQ LISPXVALUE 
(EVAL command (CDR x)))) 
((AND (ATOM x) (LISTP line) ) 
(SETQ command (recognize x)) 
(SETQ LISPXVALUE 
(EVAL command line) )) 
((AND (ATOM x) (LISTP (CAR line) )) 
(SETQ command (recognize x)) 
(SETQ LISPXVALUE 
(EVAL command (CAR line))))) 
(RETURN LISPXVALUE) ) : 


)) 


which handles the three forms of input as follows: 


1. If you typed 
<(command argumenti argument2 ... argumentN) 
then X is (command argument! ... argumentN) and LINE is NIL: 


<—(SETQ X 100) 


2. If you typed 


“command argumenti argument2 ... argumentN 
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then X is command, as in EVAL format, and LINE is (argument! ... 
argumentN). 


“USE SET FOR SETQ 


3. If you typed 


<“—command(argument1 argument2 ... argumentN) 
then X is command, as in APPLY format, and LINE is ((argumentl ... 
argumentN)). 
<PP(REAL) 
(REAL 
(LAMBDA (CX) 


(RECORDACCESS (QUOTE REAL) 
CX NIL (QUOTE FETCH) ))) 


25.3 ESTABLISHING A USER EXECUTIVE 


Within your program, you may want to establish your own executive routine that 
interprets a set of commands defined by your application. USEREXEC allows 
you to define your own prompt character, macros, and scanning function. It 
calls LISPX iteratively until it encounters the lispxmacro OK or via a RET- 
FROM. It takes the format 


Function: USEREXEC 
# Arguments: 3 


Arguments: 1) A prompt character, LISPXID 
2) lispxmacros, LISPXXMACROS 
3) a user scanning function, LISPXXUSERFN 


Value: The value of the last command. 
We might define USEREXEC as follows: 


(DEFINEQ 
(userexec (lispxid lispxxmacros lispxxuserfn) 
(PROG (readbuf) 
(* 
READBUF is used to store the 
remainder of the input line after 
execution of READLINE. 
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(* 
If you do not define your own prompt 
character, then the default is used. 

) 

(AND 
(NULL lispxid) 
(SETQ lispxid '+)) 

loop 

(* 
Print the prompt character to the 
terminal. 

) 

(PROMPTCHAR lispxid T LISPXHISTORY) 

(* 
Read and evaluate the input with 
proper protection. 


(ERSETQ 
(LISPX (LISPXREAD T) 
lispxid 
lispxxmacros 
lispxxuserfn) ) 
(GO loop) ) 
)) 


If you do not provide your own prompt character, USEREXEC assumes the 
standard system prompt character. Note that the call to LISPX is errorset pro- 
tected to prevent an error from occurring due to erroneous input. 


25.4 UNDOABLE VERSIONS OF DESTRUCTIVE FUNCTIONS 


As mentioned above, each primitive destructive function has a corresponding 
version which saves information on the history list so that the effects of that func- 
tion may be undone. LISPX substitutes the undoable version for the normal ver- 
sion on any statements that are typed in. You can make your functions undoable 
by using these undoable versions in your own functions. 


25.4.1 Undoable Sets 


SETs or SETQs may be made undoable by calling SAVESET instead of SET or 
SETQ. SAVESET stores the necessary information on the history list to undo its 
effects. It saves the old value of the variable (other than NOBIND) on the prop- 
erty list of the atom under the property VALUE. It also prints the message 
(<variable) RESET). SAVESET has the following format 
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Function: SAVESET 
# Arguments: 4 


Arguments: 1) a variable name, NAME 
2) a new value, NEWVALUE 
3) a top-level flag, TOPFLG 
4) a save flag, SAVEFLG 


Value: The new value of the variable, NEWVALUE. 
Consider the following examples: 


<-MAP.WIDTH 
NOBIND 


+-(SETQ MAP.WIDTH 512) 
512 


*-(GETPROP MAP.WIDTH 'VALUE) 
NIL 


<—(SETQ MAP.WIDTH 128) 
(MAP.WIDTH RESET) 
128 


*-(GETPROP MAP.WIDTH 'VALUE) 
512 


Because SAVESET is substituted for SET or SETQ by LISPX, it will also 
add any variables passed to it to the spelling list, SPELLINGS3. 

SAVESET also calls the File Package to update the appropriate file records 
when any variable is changed that was set as the result of loading a file. 
MARKASCHANGED is invoked to ensure that the File Package notices that the 
file must be rewritten. 

If DFNFLG (see Section 8.2. 4) is not T, SAVESET prints the message 
(<name) RESET). The old value is stored under the property VALUE on 
NAMEP’s property list. 

If TOPFLG is T, SAVESET changes the contents of the variable’s value cell 
rather than scanning the pushdown list. If DFNFLG is ALLPROP as well, then 
NEWVALUE is stored as the value of the property VALUE. This allows you to 
load files without disturbing the current values of variables. 

If SAVEFLG is NOSAVE, then the old value is not stored on the property 
list. Moreover, NAME is not added to the spelling list. However, the effects are 
still undoable because the relevant information has been stored in the history 


list. 


«-(SAVESET 'MAP.WIDTH 1024 NIL 'NOSAVE) 
1024 
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«-(GETPROPLIST 'MAP.WIDTH) 
NIL 


If SAVEFLG has the value NOPRINT, the old value is saved, but the mes- 
sage is not printed. 


A Definition for SAVESET 
We might define SAVESET as follows: 


(DEFINEQ 
(saveset (name newvalue topflg saveflg) 
(COND 
((NOT (LITATOM name) ) 
(* 


If NAME is not an atom, generate an 
error. 


) 
(ERROR "ARG NOT LITATOM' name) ) 
((NULL name) 
(ERROR "ATTEMPT TO SET NIL" newvalue) )) 
(PROG (pointer oldvalue temporary) 
(* 
Set POINTER to atom or stack frame of last 
binding. 


(SETQ pointer 
(COND 
(topflg name) 
(T 
(* 


Sean the stack for the last 
binding of the variable. 


‘ar 
(STKSCAN name 
(STKARG 0 (STKPOS 
'SAVESET) ) )))) 
(SETQ oldvalue (CAR pointer) ) 
(COND 
((AND topflg 
(EQ DFNFLG 'ALLPROP) 
(NEQ (CAR pointer) 'NOBIND) ) 
(* F 
Save the new value under the 
property VALUE on the atom's. 
property list. 








25.4 Undoable Versions of Destructive Functions 911 


(/PUT name 'VALUE newvalue) 
(RETURN newvalue) ) 
((OR 
(NOT (ATOM pointer) ) 
saveflg 'NOSAVE) ) 
x 


Check either for top-level 
binding or for a call from /SET 
or /SETQ. 


(GO getout) ) 
((OR 
(EQ oldvalue 'NOBIND) 
(EQUAL oldvalue newvalue) )) 
T 
(COND 
((NEQ DFNFLG T) 
(SETQ temporary (CONS name 
' (RESET) ) ) 
( AND 
(NEQ saveflg 'NOPRINT) 
(NULL 
(SOME 
(GET LISPXHIST 
'LISPXPRINT) 
( FUNCTION 
(LAMBDA (X) 
(AND 
(EQ (CAR X) 
'PRINT) 
(EQUAL (CADR 
X) 
temporary) )) ))) 
(LISPXPRINT temporary T)) 
(/PUTPROP name 'VALUE 
oldvalue) )))) 
(* 
ADD NAME to USERWORDS since it was typed 
in. 
) 
( AND 
DWIMFLG 
(ADDSPELL name T)) 
getout 
(AND 
(LISPXHIST 
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(UNDOSAVE 
(LIST 'UNDOSET pointer name oldvalue) 
LISPXHIST) ) 

(* 


Set the value of NAME here, finally. 
) 
(RPLACA pointer newvalue) 
(RETURN newvalue) ) 
)) 


Unsetting Values , 
You may restore the old value by invoking UNSET, which takes the form, 
Function: UNSET 
# Arguments: 1 
Arguments: 1) the name of an atom, NAME 
Value: The value of NAME. 


UNSET saves the current value under the property VALUE and sets the 
value of the variable to the contents of VALUE. It does not print any messages. 
You may use UNSET to alternate between two variable values. This is particu- 
larly useful in testing programs. Consider the following example: 


«-(SAVESET 'MAP.WIDTH 512) 
512 


«MAP .WIDTH 

512 

«<-(GETPROPLIST 'MAP.WIDTH) 
(VALUE 1024) 


<(UNSET 'MAP.WIDTH) 
MAP .WIDTH 


<-MAP.WIDTH 
1024 


«-(GETPROPLIST 'MAP.WIDTH) 
(VALUE 512) 


UNSET is called with a single argument, the NAME of the variable whose 
old value is to be restored. UNSET merely invokes SAVESET with the proper 
arguments. 


A Definition for UNSET 
We might define UNSET as follows: 
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(DEFINEQ 
(unset (name) 
(SAVESET name 
(GETPROP name 'VALUE) 
r 


NOPRINT) 
)) 


Alternative Forms 
Alternative forms for SETQ and SETQQ may be defined in terms of SAVESET. 


(DEFINEQ 
(savesetq 
(NLAMBDA (name newvalue) 


(SAVESET name (EVAL newvalue)) 
))) 


(DEFINEQ 
(savsetqq 
(NLAMBDA (name newvalue) 


(SAVESET name newvalue) 
))) 


Alternative Forms for RPAQ and RPAQQ 

Note also that RPAQ and RPAQQ (see Section 3.9) operate like SETQ and 
SETQQ except that they bind the top-level value of the variable. We can define 
them using SAVESET as follows: 


(DEFINEQ 
(rpaq 
(NLAMBDA (name newvalue) 
(SAVESET name (EVAL newvalue) T) 
))) 
(DEFINEQ 
(rpaqq 


(NLAMBDA (name newvalue) 
(SAVESET name newvalue T) 
))) 


25.4.2 Replacing the Top-Level Value 
Both RPLACA and RPLACD affect the top-level value of a variable. Their un- 
doable versions are /RPLACA and /RPLACD. They may be defined as 


(DEFINEQ 
(/rplaca (name newvalue) 
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(AND LISPXHIST 
(UNDOSAVE 
(COND 
((LISTP name) 
(CONS name 
(CONS (CAR name) 
(CDR name) ))) 
(T 
(LIST '/RPLACA 
name 
(CAR name) ))) 
LISPXHIST) ) 
(RPLACA name newvalue) 


(DEFINEQ 
(/rplacd (name newvalue) 
(AND LISPXHIST 
(UNDOSAVE 
(COND 
((LISTP name) 
(CONS name 
(CONS (CAR name) 
(CDR name) ))) 
(T 
(LIST '/rplacd 
name 
(CDR name) ) ) 
LISPXHIST) ) 


(RPLACD name newvalue) 
)) 


Note that /RPLACA and /RPLACD have the same effect as RPLACA and 
RPLACD. Moreover, if no history list is defined (i.e., the History Package is not 
being used), they are exactly equivalent. 


25.4.3 Undoing Mapping Functions 


Mapping functions (see Chapter 12) apply a function to one or more arguments 
sequentially. Side effects of the function or functions called by it may alter the 
value or structure of the individual arguments. We can define an undoable ver- 
sion of a mapping function which saves the necessary information on the history 
list by using the undoable versions of primitive destructive functions. As an ex- 
ample, consider the definition for an undoable version of MAPCONC that is 
called /MAPCONC: 
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(DEFINEQ 


(/mapcone (mapx mapfunction.1 mapfunction.2) 


(PROG (map.1st map.entry map.result) 
loop 


(COND 
((NLISTP mapx) 
(RETURN map.1st)) 
((SAVESETQ map.result 
(APPLY* mapfunction.1 
(CAR mapx) )) 
(COND 
(map.entry 
(/rplacd map.entry map.result) ) 
T 
(SAVESETQ map.lst 
(SETQ map.entry 
map.result) ))) 
(PROG NIL 
loop2 
(COND 
((SAVESETQ map.result 
(CDR map.entry) ) 
(SAVESETQ map.entry 
map.result) 
(GO loop2))))) 
(SAVESETQ mapx 
(COND 
(mapfunction.2 
(APPLY* mapfunction.2 
mapx) ) 
(T 
(CDR mapx) ))) 
(GO loop) ) 
)) 


Similar definitions may be constructed for each of the other mapping func- 
tions. 


25.4.4 Undoing Function Definitions 


Function definitions may be stored on the property list of an atom under the 
property EXPR. Two functions may set these definitions: PUTD and MOVD. 
We can construct undoable versions of these functions as follows: 


(DEFINEQ : 
(/putd (a.function a.definition) 
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(PROG (temporary) 
(SETQ temporary (GETD a.function)) 
(COND 
((NOT (ATOM a. function) ) 
(RETURN NIL) )) 
(PUTD a.function a.definition) 
(AND LISPXHIST 
(UNDOSAVE 
(LIST '/putd a.function temporary) 
LISPXHIST) ) 
. (RETURN a.definition) ) 


Note that we test A.FUNCTION to make sure it is atomic so that no error 
results when we attempt to do the PUTD. | 
Using /PUTD, we can now define /MOVD: 


(DEFINEQ 
(/movd (function.1 function.2 flag) 
(PROG (newflag) 
(SETQ newflag (NULL (GEID function.2) )) 
(/PUTD funection.2 
(COND 
(flag 
(COPY (GETD function.1))) 
(T 
(GETD function.1)))) 
(AND FILEPKGFLG 
(EXPRP function.2) 
(NEWFILE? function.2 NIL newflag) ) 
(AND DWIMFLG 
(ADDSPELL function.2) ) 
(RETURN function.2) ) 


)) 


25.4.5 Undoing the Putting and Removing of Properties 


PUTPROP (see Section 7.3) and REMPROP (see Section 7.4.2) are functions 
that put and remove properties from atoms. We would like to undo a PUTPROP 
if it overwites a property value that already exists. We would like to undo REM- 
PROP if it removes a property from the atom’s property list that should be re- 
tained. We may define these functions as follows: 


(DEFINEQ 
(/putprop (atm property value) 
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(COND 
((NULL atm) 
(ERROR "ATTEMPT TO RPLAC NIL" 
(LIST atm property) )) 
((NOT (LITATOM atm) ) 
(ERROR "ARG NOT LITATOM" 
atm) )) 
(PROG (prop.list.1 prop.list.2 temporary) 
(SETQ prop.list.1 (GETPROPLIST atm) ) 
loop 
(COND 
((NLISTP prop.list.1) 
(COND 
( (AND 
(NULL prop.list.1) 
prop.list.2) 
(SETQ temporary 
(LIST property value) ) 
( AND 
LISPXHIST 
(UNDOSAVE 
(LIST '/PUT-1 
atm 
temporary) 
LISPXHIST) ) 
(/RPLACD (CDR prop.list.2) 
temporary) 
(RETURN value) ) )) 
((NLISTP (CDR prop.list.1))) 
((EQUAL (CAR prop.list.1) property) 
(/RPLACA (CDR prop.list.1) value) 
(RETURN value) ) 
(T 
(SETQ prop.list.2 prop.list.1) 
(SETQ prop.list.1 (CDDR 
prop.list.2)) 
(GO loop) )) 
(SETQ temporary 
(CONS property 
(CONS value (GETPROPLIST atm) ))) 
(AND LISPXHIST 
(UNDOSAVE 
(LIST '/put-1 
atm 
temporary ) 
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LISPXHIST) ) 
(SETPROPLIST atm temporary) 
(RETURN value) ) 
)) 


And the definition for /REMPROP might appear as: 


(DEFINEQ 
(/remprop (atm property) 
(COND 
((NULL (LITATOM atm)) 
(ERROR "ATTEMPT TO RPLACA NIL" atm) )) 
(PROG (prop.1lst.1 prop.1lst.2 value) 
(SETQ prop.1lst.1 (GETPROPLIST atm) ) 
loop 
(COND 
((OR (NLISTP prop.1st) 
(NLISTP (CDR prop.1st))) 
(RETURN value) ) 
((EQUAL (CAR rop.1lst) property) 
(SETQ value property) 
(AND LISPXHIST 
(UNDOSAVE 
(LIST '/PUT+1 
atm 
(CDR prop.1st.2) 
prop.1lst.1) 
LISPXHIST) ) 
(COND 
(prop.1st.2 
(/RPLACD (CDR prop.1st.2) 
(CDDR prop.1st.1))) 
(T 
(SETPROPLIST atm 
(CDDR 
prop.1st.1)))) 
(SETQ prop.1lst.1 (CDDR prop.1st.1))) 
(T : 
(SETQ prop.1st.2 prop.1st.1) 
(SETQ prop.1st.1 (CDDR 
prop.ist.2))))) © 
(GO loop) ) 


)) 
/PUT-1 may be defined as 
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(DEFINEQ 
(/put-1 (atm property) 
(PROG ((x atm) ) 
loop 
(COND 
((EQUAL (CDR x) property) 
(AND LISPXHIST 
(UNDOSAVE 
(LIST '/PUT-1 
atm 
x 
property) 
LISPXHIST) ) 
(RPLACD x (CDDR property)) 
((SETQ x (CDR x)) 
‘4 (GO loop)))) 


25.4.6 Writing Your Own Undoable Functions 


You may augment the functions that are undoable by the Programmer’s Assis- 
tant by writing your undoable versions of your own functions. To do so, you will 
have to observe the following rules: 


1. Use only undoable versions of the destructive functions in the functions 
that you write. If you need to know which functions are undoable, see the 
value of LISPXFNS in Section 25.8. 

2. For your functions, write an undoable version for every function that 
modifies one of your data structures. The application user will use the 
regular versions, but LISPX will substitute the undoable versions for 
you. 

3. Make the proper entries on LISPXFNS of the regular and undoable ver- 
sions of your functions. 


25.5 PROGRAMMER’S ASSISTANT FUNCTIONS 


The Programmer’s Assistant provides access to many functions that may be 
called from within your program. This allows you to create executive and input 
routines that are tailored to your applications. You may do this by redefining the 
basic INTERLISP functions, augmenting them with additional code, or calling 
them from your own executive routine. 


25.5.1 LISPX Support Functions 


LISPX invokes a number of support functions when it substitutes for IN- 
TERLISP’s READ-EVAL-PRINT loop. These functions perform the same 
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functions as READ, EVAL, and PRINT, but are written to recognize the special 
commands supported by the Programmer’s Assistant. 

LISPXREAD is a substitute for the generalized READ function (see Section 
14.1). It has the format 


Function: LISPXREAD 
# Arguments: 2 
Arguments: 1) a file name, FILE 
2) a read table, RDTBL 
Value: The next unread expression. 


LISPXREAD obtains the next expression from the specified file. It may do 
this in one of two ways: 


1. If READBUF is non-NIL, it contains a list of expressions that have been 
unread as the result of previous Programmer Assistant commands. 
LISPXREAD returns the next expression from this list. 

2. If READBUF is NIL, LISPXREAD invokes READ (see Section 14.1) to 
acquire the next expression from the input stream. 


LISPXREAD sets REREADFLG to NIL when it reads input via READ, but 
sets it to the value of READBUF when rereading. 

The actions of LISPXREAD are mediated by a read table as described in 
Section 14.4. 


A Definition for LISPXREAD 
We might write LISPXREAD as follows: 


(DEFINEQ 
(lispxread (file rdtb1) 
(PROG (lispxinput) 
loop 
(COND 
((NULL READBUF) 
(* 
Nothing in the read buffer, so 
to read from the terminal. 
) 
(SETQ REREADFLAG NIL) 
(SETQ lispxinput 
(COND 
((EQ lispxreadfn 'READ) 
(READ T)) 
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(T 
(APPLY*¥ lispxreadfn 
file)))) 
(COND 
((READP T) 
(* 
Echo the input for the user 
with no <CR) because there 
is more input in the read 
’ buffer. 
) 
(PRIN2 lispxinput T) 
(SPACES 1 T)) 
(T 
(PRINT lispxinput T)))) 
(RETURN lispxinput) ) ) 
(SETQ lispxinput (CAR READBUF) ) 
(SETQ READBUF (CDR READBUF) ) 
(RETURN lispxinput) ) 


)) 


However, there is a bit of subterfuge going on here. LISPXREAD actually 
does not do a READ if you are accepting data from a file. Rather, it performs the 
following statement: 


(APPLY* LISPXREADFN file) 


where LISPXREADEN is initially defined as READ. You may assign any read- 
ing function that you want to LISPXREADFN to perform input to your pro- 
gram. Since the reading function may parse the input stream, do character or 
macro substitution, or other operations, this provides you with a powerful mech- 
anism for controlling how data is entered into your program from various 
sources. The reading function may even be configured to perform security and 
validation checks on the input file. 


Unreading an Expression 
LISPXUNREAD unreads a list of expressions contained in its argument, which 
is a list. It takes the form 

Function: LISPXUNREAD 


# Arguments: 1 
Argument: 1) a list of expressions to be unread, LST 


Value: The list of expressions. 
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LISPXUNREAD puts the unread expressions into READBUF. Thus, these 
expressions will be the next ones considered by LISPXREAD as input before 
going to the file. If the expressions which appear in this psuedo-input must be 
executed in a certain sequence, you are responsible for ordering them in the 
manner in which they are to be executed. 

We might define LISPXUNREAD as follows: 


(DEFINEQ 
(lispxunread (1st) 
(SETQ READBUF 


(COND 
((NULL READBUF) lst) 
(T 
(APPEND lst 
(CONS HISTSTRO 
READBUF) ) ) ) ) 
)) 
Testing for Input 


LISPXREADP is a predicate that tests whether anything is waiting to be read on 
the primary input stream. It takes the form 


Function: LISPXREADP 

# Arguments: 1 

Argument: 1) a flag, FLAG 

Value: T, if anything is waiting to be read; 


otherwise, NIL. 


If FLAG has the value T, LISPXREADP will return T if there is any input 
waiting to be read via LISPXREAD. Thus, if the user types ahead to the read 
buffer, LISPXREAD will detect its presence. 

If FLAG is NIL, LISPXREADP returns T if and only if there is input to be 
read on the current line. That is, it does not detect any expressions that you may 
have typed ahead. 

In both cases, leading spaces are ignored by reading them with READC. 

We might define LISPXREADP as follows: 


(DEFINEQ 
(lispxreadp (flag) 
(COND 
(READBUF 
(OR flag 
(NEQ (CAR READBUF) HISTSTRO) ).) 





_——— 
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(T 
‘5 (READP T))) 


25.5.2 Evaluating Expressions as if LISPXREAD 


When LISPXREAD reads input, the input is recorded on the history list as an 
event. You may enter events on the history list from your program by simulating 


the read and evaluation process. LISPXEVAL performs this simulation for you. 
It takes the form 


Function: LISPXEVAL 

# Arguments: 2 

Arguments: 1) a lispx expression, LISPXFORM 
2) a lispx identifier, LISPXID 

Value: The value produced by evaluating 
LISPXFORM. 


LISPXEVAL evaluates LISPXFORM as though it had been read by LISPX. 
That is, the expression is recorded as an event on the history list. The expression 
is made undoable by substituting the undoable versions of the corresponding 
destructive functions (see Section 25.4). The value produced by evaluating 
LISPXFORM is returned to the caller, but is not printed. 

We might define LISPXEVAL as follows: 


(DEFINEQ 
(lispxeval (lispxform lispxid) 
(PROG (lispxhist) 
(OR lispxid 
(SETQ lispxid '«)) 
(* 

Create the history list entry and 
make a copy to return to the caller. 


(SETQ lispxhist 
(HISTORYSAVE LISPXHISTORY 
lispxid 
NIL 
lispxform) ) 
(* 
Evaluate LISPXFORM and put value into 
history list entry. 
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(RPLACA lispxhist 
(EVAL 
(COND 
((NLISTP lispxform) 
lispxform) 
(T 
(LISPX/ lispxform) )) 
lispxid) ) 
(* 
Return the value computed from the 
evaluation of LISPXFORM. 


(RETURN (CAR lispxhist) )) 
)) 


25.5.3 Apprising the Assistant of Undoable Functions 


When you have defined an undoable version of some destructive function, you 
need to apprise the Programmer’s Assistant of its existence. You do this by exe- 
cuting NEW/EN with the name of the new function. It takes the form 


Function: NEW/FN 

# Arguments: 1 

Argument: 1) the name of an undoable function, FN 
Value: The name of the function. 


NEW/EN updates the internal tables of the Programmer’s Assistant so that 
a function will be undoable when typed in. The IRM suggests this example: 


< (DEFINEQ 
(/radix (x) 
(UNDOSAVE (LIST '/radix (radix x))) 
)) 


/radix 


<(NEW/FN '/radix) 
/RADIX 


«(PRINT 150) 
150 


«(RADIX 12) 
10 


«(PRINT 150) 
106 
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(Note: the prompt is printed using 
the radix also!) 
(RESET) 


“(PRINT 150) 
150 


25.5.4 Substituting Undoable Versions 


LISPX automatically performs the substitution of undoable versions of destruc- 
tive functions when it reads in an expression. To do so, it uses the function 
LISPX/, which takes the form 


Function: LISPX/ 


# Arguments: 3 


Arguments: 1) an expression, EXPRESSION 
2) a function, FN 
3) a list of bound variables, VARS 


Value: The expression with appropriate 
substitutions. 


If FN is non-NIL, it should be the name of a function. EXPRESSION will be 
its argument list. 

If FN is NIL, then EXPRESSION is an expression in which substitutions are 
to be made. 

In either case, VARS is an optional list of bound variables that may be used 
during the substitution process. 

Consider the following examples: 


«-(LISPX/ '(SETQ X (CAR LETTERS) )) 
(SAVESET X (CAR LETTERS) ) 


<(LISPX/ '(SETQ X (RPLACA HEAD (CAR TASK)))) 
(SAVESET X (/RPLACA HEAD (CAR TASK))) 


25.5.5 Undoing Events 
UNDOLISPX allows you to undo one or more events. It takes the form 


Function: UNDOLISPX 
# Arguments: 1 
Argument: 1) an event specification, EVENT 


Value: The name of the last function undone. 
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UNDOLISPX executes the UNDO command. EVENT is a list of one or 
more event specifications. UNDOLISPX invokes UNDOLISPX1 on each event 
in EVENT. 

When you are undoing events, undoing them in order is guaranteed to re- 
store you to the original state of your computation. However, undoing out of 
order is defined as restoring any cells changed in the indicated operation to their 
original state before the operation was performed. Undoing out of order will 
cause problems when several events are dependent on one another. 


<(SETQ presidents '(hayes garfield polk buchanan) ) 
(HAYES GARFIELD POLK BUCHANAN) 


«-(SETQ X (ATTACH presidents '(lincoln) )) 
((HAYES GARFIELD POLK BUCHANAN) LINCOLN) 


<(SETQ Y (ATTACH X '(MCKINLEY) )) 
(((HAYES GARFIELD POLK BUCHANAN) LINCOLN) MCKINLEY) 


<-(UNDOLISPX '(2)) 
SETQ undone. 

=i 

UNBOUND ATOM 

X 


«+ (UNDOLISPX '(4)) 

UNDOLISPX undone. 

UNDOLISPX 

“xX 

((HAYES GARFIELD POLK BUCHANAN) LINCOLN) 
<(UNDOLISPX '(6)) 


UNDOLISPX undone. 
UNDOLISPX 


-—Z 


((LINCOLN) MCKINLEY) 


In general, operations will always be independent if they affect different lists 
or sublists (which are not tails) of the same list. Note that property lists are 
treated differently because each property is assumed to be independent. 


«(SETQ REAGAN NIL) 
NIL 


«-(PUTPROP 'REAGAN 'INAUGURAL-DATE 'JAN -20-1985) 
JAN-20-1985 


«-(PUTPROP 'REAGAN 'TERM 'SECOND) 
SECOND 
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«-(PUTPROP 'REAGAN 'ELECTORAL-VOTES 525) 
525 


“-GETPROPLIST 'REAGAN) 


(INAUGURAL-DATE JAN-20-1985 TERM SECOND ELECTORAL-VOTES 
525) 


<(UNDOLISPX ! (2)) 
PUTPROP undone. 
PUTPROP 


«-(GETPROPLIST 'REAGAN) 
(TERM SECOND ELECTORAL-VOTES 525) 


Note that events are specified in a list. Here they have been specified by the 
number of the event, but you may also specify them by the name of the function 
used in the event. 


Undoing Exactly One Event 
UNDOLISPX1 allows you to undo exactly one event. It takes the form 


Function: UNDOLISPX1 

# Arguments: 2 

Arguments: 1) an event, EVENT 
2) a flag, FLAG 

Value: T or NIL. 


UNDOLISPX1 undoes one event on a history list. It handles three cases: 


1. If there is nothing to be undone, it returns NIL. 

2. If the event was already undone, it prints the message “ALREADY UN- 
DONE” and returns T. 

3. Otherwise, it undoes the event, prints the appropriate message, and re- 
turns T. 


If FLAG is T and the event is already undone, or is an UNDO command, 
UNDOLISPX1 does nothing but return NIL. When EVENT is NIL, UNDO- 
LISPX searches the history list until it finds an event for which UNDOLISPX1 
returns T. 

To undo an event, UNDOLISPX1 must map down the property value for the 
SIDE field of the history list entries. For each element, it applies the CAR to the 
CDR and marks the event undone by attaching (with /ATTACH) a NIL to the 
front of the value of the SIDE property. Undoing elements in this fashion causes 
UNDOSAVE entries to be made on LISPXHIST. This allows you to undo the 


effects of UNDOLISPX1. 
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25.5.6 Undoing When Errors Occur 


UNDONLSETQ is an NLAMBDA function that operates like NLSETQ. It 
takes the form 


Function: UNDONLSETQ 
# Arguments: 1 

- Argument: 1) an expression, UNDOFORM 
Value: The value of UNDOFORM. 


UNDONLSETOQ evaluates UNDOFORM. If no error occurs, it returns 
(LIST (EVAL UNDOFORM)) and records the undo information on the history 
list. If an error does occur, UNDONLSETOQ returns NIL (like NLSETQ) and 
undoes any changes that were made by undoable functions. 

UNDO information is stored directly on the history event (if LISPXHIST is 
not NIL), so that if you execute a CTRL-D out of the UNDONLSETQ, the event 
will still be undoable. 

The IRM suggests that UNDONLSETQ might be defined as follows: 


(DEFINEQ 
(undonlsetq 
(NLAMBDA (undoform) 
(RESETLST 
(RESETSAVE (RESETUNDO) 
(AND (EQUAL RESETSTATE 'ERROR) 
(RESETUNDO OLDVALUE) ) ) 
undoform) ) ) 


)) 


25.5.7 LISPX Printing Support 


The Programmer’s Assistant provides a number of printing functions to support 
display of information at the top-level executive. These functions have the same 
form 


Function: LISPXPRINT 
LISPXPRIN1 
LISPXPRIN2 
LISPXSPACES 
LISPXTERPRI 
LISPXTAB 
USERLISPXPRINT 


# Arguments: 4 
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Arguments: 1) an expression, EXPRESSION 
2) a file name, FILE 
3) a read table, RDTBL 
4) ano print flag, NODOFLAG 


Value: The value of EXPRESSION. 


Each of these functions performs the same action as its corollary as de- 
scribed in Chapter 15. They are redefined here to make entries on the history list 
and to provide a mechanism for modifying the top-level executive. 


«-(LISPXPRINT '(SETQ X (QUOTE (ABC D))) TTT) 
NIL 


because NODOFLAG is T. 


Definitions for LISPX Printing Functions 
We might define these functions as follows: 


(DEFINEQ 
(lispxprint (expression file rdtbl nodoflag) 
(AND LISPXPRINTFLG 
LISPXHIST 
(LISPXPUT 'LISXPRINT 
(LIST 
(NLIST 'PRINT 
expression 
file 
rdtb1) ) 
T 
LISPXHIST) ) 
(AND (NULL nodoflag) 
(PRINT expression file rdtb1) ) 


)) 
(DEFINEQ 
(lispxprini (expression file rdtbl nodoflag) 
(AND LISPXPRINTFLG 


LISPXHIST 
(LISPXPUT 'LISXPRINT 
(LIST 
(NLIST 'PRIN1 
expression 


file 
rdtb1) ) 
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T 
LISPXHIST) ) 
(AND (NULL nodoflag) 
(PRIN1 expression file rdtb1l)) 
)) 


and similarly for LIXPSPRIN2, LISPXTAB, LISPXSPACES, and LISPX- 
TERPRI, which vary only in function name, argument to NLIST, and final print 
statement. 


User-Defined LISPX Printing 

USERLISPXPRINT permits you to define additional LISPX printing functions. 
It is defined to look back on the stack, find the name of the calling function, 
strip off the leading LISPX, perform the appropriate saving information, and 
then call the function to do the actual printing. The function called is the func- 
tion name with the “LISPX”’ stripped off. 


LISPXPRINTDEF 
LISPXPRINTDEF is the corollary function to PRINTDEF. It takes the form 


Function: LISPXPRINTDEF 
# Arguments: 6 


Arguments: 1) an expression, EXPRESSION 
2) a file name, FILE 
a left-hand margin, LEFT 
a definition flag, DEFFLAG 
5) a tail flag, TAILFLAG 
ano print flag, NODOFLAG 


Value: The value of the expression. 


All of the printing functions put their output on the history list under the 
property *LISPXPRINT*. 

If NODOFLAG is non-NIL, these functions merely put their output on the 
history list, but do not print anything. 

To perform output from a user program so that the output appears on the 
history list, you merely call the corresponding LISPX printing function rather 
than the standard printing function. 

LISPX printing is mediated by the value of LISPXPRINTFLG. If NIL, the 
LISPX printing functions will not store their output on the history list. 


25.6 CONTROLLING PROMPTING 


History lists (see Chapter 28) contain numbered events that may be referred to by 
history commands. Normally, INTERLISP does not identify each statement 
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(also called “events” by the History Package). You may enable statement num- 
bering by setting the variable PROMPT#FLG to T. The current event number 
will be printed preceding the prompt character. For example, 


<MAKEFILE[AMISMAINT] 
[DSK] AMISMAINT. ;20 


<-(SETQ PROMPT#FLG T) 
T 


3'7*-MAKEFILE[AMISUSER] 
[DSK] AMISUSER. ;7 


Normally, a prompt is displayed by INTERLISP, you type an expression in 
response, and the expression is evaluated. That is, expressions are valuated after 
the prompt character has been displayed. You can force the evaluation of ex- 
pressions before the prompt character is printed by assigning the expressions to 
be evaluated to PROMPTCHARFORMS. Initially, PROMPTCHARFORMS 
has the value (CHECKNIL). CHECKNIL is a system function that checks to see 
if the CAR or CDR of NIL have been reset or rebound. If so, it restores them and 
prints a warning message. 


25.7 THE RESET PACKAGE 


While your program is running, it may be interrupted or aborted because of 
errors or the pressing of control characters at the keyboard. The most devastat- 
ing control character is CTRL-D because it forces a return to the top-level 
READ-EVAL-PRINT loop. However, your environment remains the same as 
established by your program. That is, any system variables that your program 
sets directly via SETQ or indirectly via a function call, and any global variables 
that your program defines will retain their values. Generally, you want to protect 
your environment by resetting variables to their original values when your pro- 
gram completes execution. 

Errors may be caught (intercepted!) via ERRORSET. However, CTRL-Ds 
cannot be intercepted. The Reset Package provides functions to restore your en- 
vironment in the event a CTRL-D or (RESET) is executed. However, you may 
also restore pieces of your environment when an error occurs using this package. 
While the Reset Package is useful when a (RESET) or CTRL-D occurs, it is 
quite valuable for performing selective restorations in the event of errors. 


25.7.1 Establishing a Reset List 
RESETLST establishes a reset list. It takes the following form 


Function: RESETLST 
# Arguments: 1-N 
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Arguments: 1) a list of reset expressions, FORM[i] 
Value: Value of last form, FORM[n]. 


RESETLST is an NLAMBDA, nospread function. RESETLST sets up an 
ERRORSET (see Section 18.3) so that any reset operations performed by RE- 
SETSAVE will be restored when an error, (RESET), or a CTRL-D occurs. 

If no error occurs, the value of RESETLST is the value of the last form. 
Otherwise, an error is generated after the necessary restorations are performed. 
That is, the environment before execution of the RESETLST will be restored if 
an error occurs. 


25.7.2 Restoring Your Environment 


RESETSAVE changes your environment by calling a function or setting a vari- 
able. At the same time, it sets up a specification for restoring the original value 
should an error or reset occur. RESETSAVE is usually used within a call to 
RESETLST. It takes the form 


Function: RESETSAVE 

# Arguments: 2 

Arguments: 1) an expression, X 
2) an expression, Y 

Value: aK. useful quantity (according to the 
IRM). 


RESETSAVE is an NLAMBDA, nospread function, so its arguments are 
not evaluated before it is called. Rather, RESETSAVE evaluates its arguments 
according to the following cases: 


X is Atomic 
The top-level value of X is set to Y. Y is evaluated but X is not. When you enter 
the Editor, it performs 


(RESETSAVE LISPXHISTORY EDITHISTORY) 


to set the current history list to that used by the Editor. When you exit the Edi- 
tor, the current history list will be restored as LISPXHIST. 


X is Not Atomic 

It is evaluated. If Y, e.g., the CDR of the form, is NIL, then X must return its 
former value while setting a new one. Thus, the effect of evaluating the form may 
be reversed when an error or reset occurs. 
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(RESETSAVE (CONTROL T)) 


will eliminate line buffering for the terminal table. It returns NIL, which is its 
normal state. 


X is a Function 


If X does not return its former value, the restoring expression is the value of Y. Y 
is evaluated before X. 


(RESETSAVE (SETBRK ...) 
(LIST 'SETBRK (GETBRK) )) 


which restores the break characters by applying SETBRK to the value returned 
by (GETBRK). This expression is computed before (SETBRK) is evaluated. 


X may be NIL 


If Y is non-NIL. Y is executed whenever a reset occurs. The IRM notes that a 
useful form is 


(RESETSAVE NIL (LIST 'CLOSEF <filename)) ) 

which closes a file whenever a reset occurs. Alternatively, you may wish to use 
(RESETSAVE NIL (LIST 'CLOSEALL) ) 

which closes all files whenever a (RESET) occurs. 


MAKEFILEFORMS as an Example 

In the File Package, the variable MAKEFILEFORMS is evaluated to set certain 
system variables whenever a MAKEFILE is performed. It inspects the options 
passed to MAKEFILE to set these variables. To ensure that their values are reset 
when MAKEFILE exits, they are set inside a RESETSAVE as follows: 


(ADDVARS 
(MAKEFILEFORMS 
(COND 
((MEMBER 'NOCLISP OPTIONS) 
(RESETSAVE PRETTYTRANFLG T)) 
((MEMBER 'CLISP% OPTIONS) 
(RESETSAVE PRETTYTRANFLG 'BOTH))) 
(COND 
((MEMBER 'FAST OPTIONS) 
(RESETSAVE PRETTYFLG NIL) )) 
(COND 
((OR 
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(MEMBER 'CLISPIFY OPTIONS) 
(MEMBER 'CLISP OPTIONS) ) 
« (RESETSAVE CLISPFIYPRETTYFLG T) ) 
OR 

(EQUAL FILETYPE 'CLISP) 
(MEMBER 'CLISP (LISTP FILETYPE) ) ) 
(RESETSAVE CLISPIFYPRETTYFLG 
'CHANGES) ) ) 

(AND , 

(NEQ (LINELENGTH) FILELINELENGTH) 

(RESETSAVE LINELENGTH FILELINELENGTH) ) ) ) 


25.7.3 Resetting Variables 


RESETVAR allows you to save and restore global variables. It actually com- 
bines the effects of RESETLST and RESETSAVE in a simplified form. It takes 
the form 


Function: RESETVAR 
# Arguments: 3 


Arguments: 1) a variable, VAR 
2) a new value, VALUE 
3) an expression, EXPR 


Value: The value of EXPR. 
RESETVAR is an NLAMBDA function. The function call 
(RESETVAR var value expr) 
is equivalent to executing 
(RESETLST (RESETSAVE var value) expr) 


You may evaluate a function with regard to EDITHISTORY rather than 
LISPXHISTORY using the following form: 


(RESETVAR LISPXHISTORY EDITHISTORY (<function)) ) 


Consider the following example from FNVARS which defines the IN- 
TERLISP environment at loadup: 


(22T 
(PROG (TEM) 
(RESETVAR 
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PRETTYTRANFLG 
(PRINTDEF 
(COND 
((NULL (CDAR (SETQ TEM 
(LISPXFIND LISPHISTORY 


LISPXLINE 
'ENTRY 
T)))) 
(CAAR TEM) ) 
(T (CAR TEM))) 
NIL 
T)) 
(TERPRI T) 


(RETURN (CADDR TEM) ))) 


which implements the ??T macro of the History Package. 


An Alternative Form for RESETVARS 
An alternative form, RESETVARS, operates like a PROG form on global vari- 
ables. It takes the form 


Function: RESETVARS 
# Arguments: 1-N 
Arguments: 1) a global variable list, VARSLST 
2) a set of expressions, EXPRESSION[i] 
Value: The value of EXPRESSION[n]. 


RESETVARS sets up a RESETSAVE for each of the variables mentioned in 
VARSLST. Note that this function is treated differently in shallow-bound (IN- 
TERLISP-10/VAX/370) versus deep-bound (INTERLISP-D) systems; you 
should consult the IRM for more information. 

The purpose of RESETVARS is to allow transportability of programs from 
shallow-bound to deep-bound systems, and vice versa. 


25.7.4 Resetting Expressions 


RESETFORM isa shorthand for RESETLST and RESETSAVE when the func- 
tion returns its previous setting. It takes the form 


Function: RESETFORM 
# Arguments: 2-N 


936 The Programmer’s Assistant 


Arguments: 1) a list of expressions, RESETFORMX 
2) a set of expressions, EXPRESSION[i] 
Value: If no error occurs, the value returned by 


evaluating EXPR[n]. 


RESETFORM is an NLAMBDA, nospread function. It is used when the 
corresponding function returns as its value the previous setting of some internal 
variable. It is equivalent to executing 


(RESETLST 
(RESETSAVE <resetformx) 
expression[1] 


expression[N]) 
Consider the following example from FNVAR: 


(GREETFORM 
' (LISPXEVAL 
(PROGN 
(SETQ RESETFORMS 
(REMOVE GREETFORM RESETFORMS) ) 
(COND 
((NEQ SYSTEMTYPE 
(SETQ SYSTEMTYPE (SYSTEMTYPE) )) 
(SELECTQ 
(TOPS20 
(SETQQ SYSOUT.EXT EXE) ) 
(TENEX 
(SETQQ SYSOUT.EXT SAV)) 
(SHOULDNT) ) 
(RESTETERMCHARS) 
(RESETTERMCHARS ASKUSERTTBL) ) ) 
'GREET) ) 


he) 


25.7.5 Establishing UNDO Information 


RESETUNDO initializes the saving of UNDO information when used in a re- 
setlist. It takes the form 


Function: RESETUNDO 
# Arguments: 2 
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Arguments: 1) an expression, EXPRESSION 
2) a stop flag, STOPFLAG 
Value: A value for undoing side effects. 


The value produced by RESETUNDO, when given back to RESETUNDO, 
will cause any intervening side effects to be undone. 


(RESETLST 
(RESETSAVE (RESETUNDO)) . <forms)) 


will undo the side effects of evaluating (forms) when a normal exit occurs, when 
an error occurs, or a CTRL-D is executed. 

If STOPFLAG has the value T, RESETUNDO stops accumulating undo 
information that it has been saving about the expression. 

(RESETUNDO) initializes the saving of undo information. 


25.7.6 Structure of RESETFORMS 


RESETFORMS is a list of expressions that is evaluated whenever a system reset 
occurs, either via (RESET) or CTRL-D. The structure of RESETFORMS is 


((SETQ READBUF NIL) 
(SETQ READBUFSOURCE NIL) 
(SETQ TOPLISPXBUFS 

(OR (CLBUFS T) 


TOPLISPXBUFS) ) 
(COND 
((EQ CLEARSTKLST T) 
(COND 
((EQ NOCLEARSTKLST NIL) 
(CLEARSTK) ) 
(T 
(MAPC (CLEARSTK T) 
(FUNCTION 
(LAMBDA (X) 
(AND 
(NOT (MEMB X 
NOCLEARSTKLST) ) 
(RELSTK X)))))))) 
(T 


(MAPC CLEARSTKLST (FUNCTIONRELSTK) ) 
(SETQ CLEARSTKLST NIL) )) 
(SETQ STACKOVERFLOW) ) 
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25.8 PROGRAMMER’S ASSISTANT VARIABLES 


The Programmer’s Assistant uses a number of variables to control the evaluation 
of input. 


LISPXFNS This variable is a list of all the 
functions for which LISPX will 
substitute a function if the function 
name read appears in the list. 
Principally, it is used to determine 
when to substitute undoable versions 
of functions for basic INTERLISP 
functions. 


«+ LISPXFNS 
((SETQ . SAVESETQ) (SET . SAVESET) (SETQQ . SAVESETQQ) 
(DEFINEQ . /DEFINEQ) (DEFINE . /DEFINE) (PUT . SAVEPUT) 
(PUTPROP . /PUTPROP) (RETFROM . BREAKRETFROM) (RETEVAL . 
BREAKRETEVAL) (ADDPROP . /ADDPROP) (ATTACH . /ATTACH) 
(CLOSER . /CLOSER) (CONTROL . /CONTROL) (DELETECONTROL . 
/DELETECONTROL) (DREMOVE . /DREMOVE) (DREVERSE . 
/DREVERSE) (DSUBST . /DSUBST) (ECHOCONTROL . /ECHOCONTROL) 
(ECHOMODE . /ECHOMODE) (FNCLOSER . /FNCLOSER) (FNCLOSERA 
. /FNCLOSERA) (FNCLOSERD . /FNCLOSERD) (LCONC . /LCONC) 
(LISTPUT . /LISTPUT) (LISTPUT1 . /LISTPUT1) (MAPCON . 
/MAPCON) (MAPCONC . /MAPCONC) (MOVD . /MOVD) (NCONC . 
/NCONC) (NCONC1 . /NCONC1) (PUTASSOC . /PUTASSOC) (PUTD . 
/PUTD) (PUTDQ . /PUTDQ) (PUTHASH . /PUTHASH) (RADIX . 
/RADIX) (RAISE . /RAISE) (REMPROP . /REMPROP) (RPLACA . 
/RPLACA) (RPLACD . /RPLACD) (RPLNODE . /RPLNODE) (RPLNODE2 
. /RPLNODE2) (SETA . /SETA) (SETATOMVAL . /SETATOMVAL) 
(SETBRK . /SETBRK) (SETD . /SETD) (SETPROPLIST . | 
/SETPROPLIST) (SETREADTABLE . /SETREADTABLE) (SETSEPR . 
/SETSEPR) (SET SYNTAX . /SETSYNTAX) (SETTERMTABLE . 
/SETTERMTABLE) (SETTOPVAL . /SETTOPVAL) (TCONC . /TCONC) 
(REPLACEFIELD . /REPLACEFIELD) (DELFILE . /DELFILE) 
(UNDELFILE . /UNDELFILE)) 


LISPXCOMS This variable is used to correct the 
spelling of Programmer's Assistant 
commands. 
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<—LISPXCOMS 

(XPR XPRESS DIR $ ... ?? FIX FORGET NAME ORIGINAL REDO 
REPEAT RETRY UNDO USE fix forget name redo repeat retry 
undo use SHH RETRIEVE BEFORE AFTER TYPE-AHEAD ??T CONTIN) 


LISPXPRINTFLG This variable determines whether the 
LISPX printing functions save their 
output on the history list or not. 
If it is NIL, the output will not be 
saved. 


LISPXHISTORY The standard history list for top 
level input to INTERLISP. 


25.9 LISPX STATISTICS 


In INTERLISP-10, the Programmer’s Assistant keeps various statistics about 
system usage. 


25.9.1 Printing LISPX Statistics 


You may print a summary of the LISPX statistics using LISPXSTATS, which 
takes the form 


Function: LISPXSTATS 

# Arguments: 1 

Argument: 1) a value return flag, RETURNVALUESFLAG 
Value: A list of statistics or NIL. 


LISPXSTATs will print a summary of the statistics accumulated by the Pro- 
grammer’s Assistant at your terminal. If RETURNVALUESFLAG is T, the sta- 
tistics will be returned as a list where each element has the form 


(<value) . <explanation)) 


Consider the following example: 


< (LISPXSTATS) 
(32 LISPX INPUTS) 
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(153 UNDO SAVES) 
(20 CHANGES UNDONE) 
(1 EDIT UNDO SAVES) 


(5 CALLS TO DWIM) 
(5 WERE DUE TO ERRORS) 


OF THOSE DUE TO ERRORS: 
(5 WERE DUE TO ERRORS IN TYPE-IN) 


OF THE CALLS DUE TO DWIMIFYING: 


(0:21:3 CONSOLE TIME) 
(0:0:0 OF IT IN THE EDITOR) 
(0:0:5 CPU TIME) 

(0:0:) OF IT IN DWIM) 

T 


25.9.2 Adding New Statistics 


You may add new statistics to those kept by the Programmer’s Assistant using 
ADDSTATS, which takes the form 


Function: ADDSTATS 

# Arguments: 1-N 

Arguments: 1-N) a statistic entry, STATISTIC[i] 
Value: The value of STATISTIC. 


ADDSTATS is an NLAMBDA, nospread function. Each STATISTIC{i] is a 
list of the form 


(<statistic-name) . <(message)) 
where each <statistic-name) defines a new statistic. 


+-(ADDSTATS (EDITOR-CALLS CALLS TO THE EDITOR) ) 
((EDITOR-CALLS CALLS TO THE EDITOR) ) 


25.9.3 Updating Statistics 


Both the user and the Programmer’s Assistant may update statistics variables 
using LISPXWATCH, which takes the form 


Function: LISPXWATCH 
# Arguments: 2 
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Arguments: 1) a statistic name, STATISTIC 
2) a number, N 
Value: The new value of the statistic. 


LISPXWATCH updates the specified statistic by N. If N is NIL, a default of 
1 is assumed. Consider the following example: 


«-(LISPXWATCH 'EDITOR-CALLS 2) 
NIL 


+ (LISPXSTATS) 


(2 CALLS TO THE EDITOR) 
vi 


because new statistics are added to the end of the list SYSTATS which contains 
the format for the LISPX statistics. 
25.9.4 System Statistics 


The Programmer’s Assistant currently supports the following statistics which 
are kept as elements of the list SYSTATS: 


<-SYSTATS 

((LISPXSTATS LISPX INPUTS) 
(UNDOSAVES UNDO SAVES) 
(UNDOSTATS CHANGES UNDONE) 
(EDITCALLS CALL TO EDITOR) 
(EDITSTATS EDIT COMMANDS) 
(EDITUNDOSAVES EDIT UNDO SAVES) 
(EDITUNDOSTATS EDIT CHANGE SUNDONE) 
(P.A.STATS P.A. COMMANDS) 
(CLISPIFYSTATS CALLS TO CLISPIFY) 
(FIXCALLS CALLS TO DWIM) 
(ERRORCALLS WERE DUE TO ERRORS) 
(DWIMIFYFIXES WERE FROM DWIMIFYING) 
(FIXTIME) 

NIL 


"OF THOSE DUE TO ERRORS:" 


(TYPEINFIXES WERE DUE TO ERRORS in TYPE-IN) 
(PROGFIXES WERE DUE TO ERRORS IN USER PROGRAMS) 
(SUCCFIXES1 OF THESE CALLS WERE SUCCESSFUL) 

NIL 


"OF THESE CALLS DUE TO DWIMIFYING:"' 
(SUCCFIXES2 WERE SUCCESSFUL) 
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(SPELLSTATS 


(CLISPSTATS 
(INFIXSTATS 
(IFSTATS 
(I.S.STATS 
(MATCHSTATS 
(RECORDSTATS 
(SPELLSTATS1 


(RONONSTATS 


(VETOSTATS 


OF ALL DWIM CORRECTIONS WERE SPELLING 
CORRECTIONS) 

WERE CLISP TRANSLATIONS) 

OF THESE WERE INFIX TRANSFORMATIONS) 
WERE IF/THEN/ELSE STATEMENTS) 

WERE ITERATIVE STATEMENTS) 

WERE PATTERN MATCHES) 

WERE RECORD OPERATIONS) 

OTHER SPELLING CORRECTIONS, E.G., 
EDIT COMMANDS) 

OF ALL SPELLING CORRECTIONS WERE RUN- 
ON CORRECTIONS) 

CORRECTIONS WERE VETOED) ) 








26 





Masterscope 


One of the most useful techniques for programmers is the ability to analyze 
source programs. Conventional languages often provide such support for source 
programs. Implementation is difficult because of the wide variety of data struc- 
tures and statements one encounters in a traditional programming language 
such as FORTRAN or PASCAL. This diversity means that source program anal- 
ysis systems become quite complex because they must deal with different types of 
information for each statement. Few conventional programming languages sup- 
port this facility at run-time because of the extensive amount of information re- 
quired to answer ad hoc queries. 

INTERLISP, because it is an integrated programming environment, re- 
moves the dichotomy between source and run-time programs. This allows it to 
interface with the Editor and the File Package to dynamically track changes to 
programs as they are created and modified. 

Masterscope maintains a database of the relations that it ‘‘notices’’ when a 
function is analyzed. It develops sets of primitive relations, such as USE AS 
PROPERTY, which it modifies as changes are made to the source code. The 
resulting database allows you to determine 


What functions a given function calls 

How and where variables are bound 

How and where variables are set and/or referenced 
Which record declarations are used by functions. 


You may interrogate the Masterscope database via a simple command lan- 
guage. You may also display the hierarchy of invocation for any function. 

Because Masterscope analyzes only source programs, it will not work on 
compile code. That is, only EXPR definitions of functions are analyzed. If there 
is no in-core definition, Masterscope attempts to read the definition from a file 
that it knows about (see Chapter 17). It will search only those files that have been 
noticed or are represented on FILELST. 
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Masterscope is interfaced with both the Editor and the File Package so that 
when a function is edited or a new definition(s) loaded into your environment, 
Masterscope knows that it must (re)analyze the function(s). 


26.1 MASTERSCOPE CONCEPTS 


Masterscope relies on a few basic concepts to support the analysis of programs. 
These are 


Relations 
A relationship between functions and variables establishing usage and/or inter- 
action. 


Set 
A collection of “‘things’’ to be operated on by a Masterscope command (see be- 
low). 


Path 
The hierarchical control structure through a program whence execution may 
flow. 


Template 
Templates are patterns that describe how a function is evaluated. 


26.2 INTERACTING WITH MASTERSCOPE 


You may interact with Masterscope via an English-like command language. 
Masterscope commands consist of verbs that direct it to answer questions using 
the database or to perform analyses that result in creating or updating the data- 
base. This section defines the various commands. Section 26.3 discusses set 
specifications. 


26.2.1 Analyzing Functions 


ANALYZE directs Masterscope to analyze the functions given as its arguments. 
It takes the form 


«<, ANALYZE (set specification) 
«<. REANALYZE (set specification) 


The set specification identifies the functions to be analyzed. The informa- 
tion is entered into the database. Functions called by functions (ad infinitum) 
described by the set specification are included in the analysis. Masterscope does 
not analyze functions that it thinks it already knows about (e.g., that have infor- 
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mation already in the database). To force it to look at a function again, you must 
execute the REANALYZE command. 

Consider the following example: 


«<. ANALYZE INHERIT 


<—. SHOW PATHS FROM INHERIT 


1. INHERIT ALLSLOTS? 

“2 ALLDEMONS? 

3. INHERIT-SLOT SLOT? ALLSLOTS? 

4. | | PUTVALUE PASSITDOWN DO-OFFSPRING DO-SUBNODE [a] 
aye | | ALLSLOTS? 

6. | MAKESLOT ENTER 

Te | | MS1 MS2 MAKESLOT [6] 

8. | GETVALUE 

9. | REPLACADDD REPLACA 

10. INHERIT-DEMON SLOT? [3] 

43: MAKEDEMON PASSDEMONDOWN DO-OFF-OF-DEMON [b] 
12. REPLACADDD [9] 

wenn $$ = = === = overflow-a 
13. DO-SUBNODE SLOT? [3] 

14. MAKESLOT [6] 

15: REPLACADDD [9] 

16. ADDVALUE PASSITDOWN [4] 

iy ALLSLOTS? 

18. GETVALUE 

Pree nner ese n enn n enon eeesesesses= overflow-b 


19. DO-DEMON MAKEDEMON [11] 
20. REPLACADDD [9] 


Whenever a function is referred to in a command as a subject of a relation, it 
is automatically analyzed if an analysis has not previously been performed. 

If Masterscope cannot find the function, it displays the message ‘‘<func- 
tion) CAN’T BE ANALYZED”. If the function was previously known (de- 
scribed in the database), but cannot now be found (because its definition has 
been reset or the file closed) Masterscope displays the message “*¢function) DIS- 
APPEARED!”. 

You may also analyze the functions in a file. A number of forms are avail- 
able to perform this operation. Consider 


<. ANALYZE ALL IN AMISNETFNS 


which analyzes all of the functions contained in the list that is the value of 
AMISNETENS. If the file contains individual (FNS ...) commands as part of its 
File Package commands, you may use the form 
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<—. ANALYZE ALL IN (FILEFNSLST ' AMISDB) 


where FILEFNSLST (see Section 17.7.3) gathers the individual FNS commands 
together to form one list. 


26.2.2 Erasing the Database 


You may delete information from the database by executing the ERASE com- 
mand, which takes the form 


<. ERASE (set specification) 


ERASE removes all information described by the set specification from the 
database: 


«<—. ERASE INHERIT 
OK 


<—. WHO CALLS INHERIT 
NIL 


Caution: Executing ERASE without any arguments is tantamount to clear- 
ing the entire database. This occurs because the set specification is null which 
implies that everything should be removed. 


26.2.3 Showing Structures 


Masterscope allows you to display the structure of a program (or a subset of it) 
either as a tree or a list of functions and/or variables. 

The SHOW PATHS command displays the tree of functions (as above) us- 
ing a path specification. It takes the form 


<. SHOW PATHS <path specification) 


Path specifications are described in Section 26.5. The example in Section 
26.2 shows a simple execution of SHOW PATHS for the function INHERIT. 

The SHOW WHERE command allows you to display those functions that 
meet specified criteria given by a structure specification. The format of the 
SHOW WHERE command is 


«+. SHOW WHERE <seti) <relation) <set2) 
where the form <set1)<relation)set2) is the structure specification. <set1) 


must refer to a set of functions. <set2) may refer to functions or variables. 
Sets and relations are described in Sections 26.3 and 26.4 respectively. 
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<—. ANALYZE ALL IN COMPLEXFNS 


PVT Se ee ree ee Ce ee done 
<—. SHOW WHERE REAL IS CALLED 
CPLUS: 

(REAL CX1) 

(REAL CX2) 
CDIFFERENCE: 

(REAL CX1) 

(REAL CX2) 
CMULT: 

(REAL CX1) 

(REAL CX2) 

(REAL CX1) 

(REAL CX2) 
PRINT.COMPLEX: 

(REAL CX1) 
done 


The DESCRIBE command allows you to display information about func- 
tions described in a set specification. It takes the form 


<. DESCRIBE <set specification) 


DESCRIBE prints out the bindings of variables in the function, the vari- 
ables used freely by the function, and the functions called by the function. Con- 
sider the following example: 


« .DESCRIBE INHERIT 


INHERIT [NODE, FROM, ITYPE] 
calls: MEMB , PRINT ,MAPCAR, PUTPROP, ALLSLOTS?, 
ALLDEMONS?, ASSOC,GETPROP,CONS,LIST,SUBST, 
INHERIT-SLOT, INHERIT-DEMON 


binds: OFFLIST, IPROPS 
uses free: ALLNODES 
file: NETWORK. LISP 


26.2.4 Editing Functions 
Masterscope allows you to perform global editing of functions using set or struc- 
ture specifications. The two forms of the EDIT command are 


<. EDIT WHERE <set1)<relation)<set2) 
[-<editcommands) ] 
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and 
<. EDIT <set) [-<editcommands)] 


Set and relation specifications are discussed in Sections 26.3 and 26.4, re- 
spectively. 

(editcommands) is an optional list of edit commands that are applied to 
each function in turn. 


26.2.5 Checking Sets 


You may check a file for various anomalous conditions. CHECK takes the form 
<. CHECK <set) 
If <set) is not given, FILELST is used. Consider the following example: 
<—. CHECK AMISNET 
(<q, 


< In (no block—DEMON? KILLDEMON MAKEDEMON ...) )>)>)>) 


(note) 
NODE-not declared, used freely by-INHERIT.SLOT 
INHERIT.DEMON DO.SUBNODE, etc. 


INHERITANCE-" ''\-INHERIT.SLOT INHERIT.DEMON 
GIVE.TO.OFFSPRING etc. 


(possible error) 

— « ) = 

not declared, never bound, no top-level value, used 
freely by SHOW.OPEN.DATABASE.STRUCTURE 


! -not bound, not a GLOBALVAR, used freely by- 
SHOW.OPEN.DATABASE.STRUCTURE — 


Note that the last two errors result from CLISP structures which are not 
properly recognized by Masterscope. 


26.2.6 Using CLISP in Masterscope 


You may use the CLISP iterative statement operators in Masterscope through 
the FOR command. It takes the form 


«+, FOR (variable) <set) (i.s.tail) 
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An iterative statement is constructed where (variable) is iteratively assigned 


to ea element of (set) and then the iterative statement tail <i.s.tail) is exe- 
cuted. 


*—. FOR X CALLED BY MY.EXECUTIVE WHEN CCODEP 
DO (PRINTOUT T X ... (ARGLIST X) T) 


which prints out the name and arguments of all compiled functions that are 
called by the function MY.EXECUTIVE. 


26.2.7 Obtaining Help 


You may obtain rudimentary help by executing the HELP command, which 
takes the form 


+. HELP 


This command prints out a summary of the commands available in Master- 
scope. 


a <command) is: 


[REJANALYZE <functions) 

ERASE < functions) 

SHOW PATHS <pathoptions) 

<set) [(relation) | IS | ARE] <set) 

EDIT WHERE <functions) [{relations) <set)] [-<edit 
commands ) ] 

SHOW WHERE <functions) <relation) <set) 

CHECK <«files) 

FOR (variable) (set) (iterative statement tail) 


a (set) is (at least one of): 


a determiner + a type + a specification 
THE FUNCTIONS ['] [<atom) | <list>] 
ANY VARIABLES @ <predicate) 
WHICH PROPERTY NAMES IN <expression) 
WHO RECORDS {relation} ING <set) 
FIELDS {relation)ED [BY | 
IN] <set) 
FILES THAT (relation) 


<set) 
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I.S.OPRS LIKE <edit pattern) 
ON <files) 
ON PATH 
{pathoptions) 
FIELDS OF <records) 
<blockword) [ON <files) | OF 
« functions) ] 
{functions), <(files), etc. are <set)s whose type is 
implied. 


a <relation) is a verb and optional modifier: 


verbs: modifiers (anywhere after the verb): 

CALL [SOMEHOW | FOR EFFECT | FOR VALUE 
DIRECTLY | INDIRECTLY] 

USE AS [RECORD | PROPERTY | {record) FIELD] 
{name) 

USE AS CLISP <word) 

USE [FREELY | LOCALLY] 

SET [FREELY | LOCALLY] 

SMASH [ FREELY | LOCALLY] 

TEST [ FREELY | LOCALLY] 

REFERENCE [FREELY | LOCALLY] 

DECLARE AS [LOCALVAR | SPECVAR] 

BIND 

FETCH 

REPLACE 

CREATE 

CONTAIN 

{pathoptions) | abbreviations & synonyms 

FROM < function) | FNS = FUNCTIONS 

TO <functions) | PROPS = PROPERTIES 

AVOIDING (functions) | VARS = VARIABLES 

NOTRACE < functions) | (& singular FN, VARIABLE, 

etc) 
SEPARATE <functions) | FREE = FREELY 
LINELENGTH <number) | LOCAL = LOCALLY 


| AMONG = AVOIDING NOT 


{sets) may be joined by AND or OR or preceded by NOT. 
Pais commands can be followed by OUTPUT <filename). 
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26.3 SPECIFYING SETS 


A set specification is a phrase that describes a set to be operated upon by Mas- 
terscope commands. A set specification consists of a determiner, a type, anda 
specification. 

A determiner is one of following: THE, ANY, WHICH, WHO, or WHOM. 
It defines the scope of the set. If the determiner is omitted, ANY is assumed. Set 
phrases may be preceded by a determiner. WHICH and WHO are interrogative 
determiners that are only valid for certain commands. ANY, WHO, and 
WHOM can be used alone as they are wild-card elements. 

A type is an INTERLISP datatype. The datatypes currently supported are 
FUNCTIONS, VARIABLES, PROPERTY NAMES, RECORDS, FIELDS, or 
FILES. Any set phrase has a type, e.g., the INTERLISP datatype of the objects 
that the command will operate upon. Types are used as follows: 


1. Set types are used to differentiate between possible 
parsings. Consider the examples 


WHO SETS ANY BOUND IN INHERIT OR USED BY GETVALUE 
WHO SETS ANY BOUND IN INHERIT OR CALLED BY GETVALUE 


Both of these commands have the same form. However, 
the first example is parsed as 


WHO SETS ANY (BOUND BY INHERIT OR USED BY GETVALUE) 


since BOUND BY and USED BY refer to variables, while 
the second example is parsed as 


WHO SETS ANY BOUND IN (INHERIT OR CALLED BY GETVALUE) 


since CALLED BY and INHERIT must refer to functions. 

2. The type is used to determine the modifier for USE. 

3. The interpretation of CONTAIN(S) depends on the type 
of the object. For example, WHAT FUNCTIONS ARE 
CONTAINED IN FRAMEFNS. WHO IS CONTAINED IN FRAME would 
print all object contained in the file FRAME. 

4. The context in which a set expression is interpreted 
depends on the type. For example, ANY VARIABLES @ GETD 
is interpreted as the set of all variables that have 
been noticed by Masterscope as being bound or utilized 
in any function which has been analyzed. 
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Sets may be joined by AND or OR or preceded by NOT to form new sets. 
AND is always interpreted as meaning the intersection of the two sets, i.e., all 
elements must satisfy both set specifications. OR is interpreted as the union of 
the two sets, i.e., any element must satisfy either of the two set specifications. 
NOT is interpreted as the complement of the set specification. 


WHO CALLS GETVALUE AND PUTVALUE 


means all those functions which call both GETVALUE and PUTVALUE. 
You may not join modifiers with conjunctions in Masterscope even though 
these constructs are allowed in English. 
A specification is a description of the characteristics of the set. Specifica- 
tions are drawn from the following list: 


'<atom) You may specify a single object 
by its name. For example, 


WHO CALLS 'MAKE-SLOT 


will display the functions that 
invoke the function MAKE-SLOT. 


You may leave the ' out of the 
specification, but this form may 
yield ambiguities. Good practice 
suggest that you always quote 
the atom. 


'<list) You may specify several atoms by 
including them in a list 
structure. For example, 


WHICH FUNCTIONS CALL Be 
PUTVALUE) 


which returns a list of the 
functions that call either 
GETVALUE or PUTVALUE or both. 


IN <expression) You may specify an S-expression 
to be evaluated which returns a 
list of elements specifying the 
set. For example, 


IN ASPTPFNS 





@< predicate) 


LIKE (atom) 


{relation)ING <set) 


{relation)ED BY <set) 
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returns a list of functions 
associated with the file ASPTP 
via the File Package 
specification. 


You may specify a predicate 
which the elements of the set 
must satisfy. The <(predicate) 
may be a function name, either 
system or your own definition, a 
LAMBDA expression, or an 
expression in terms of the 
variable X. For example, 


WHO IN FRAMEFNS CALLS ANY NOT 
@GETD 


should display all functions 
having EXPR definitions. 


The @ in the specification 
indicates that members of the 
set are those functions for 
which the predicate is non-NIL. 


The <atom) is used as a pattern 
to be matched against the names 
of function. For example, 


WHO LIKE /R$ IS CALLED BY ANY 
yields the functions /RPLACA and 
/RPLNODE. 


{relation) is one of USE, CALL, 
BIND, SET possibly modified (SEE 
Section 26.4). The specified set 
consists of those objects that 
have the specified relation to 
{set). For example, 


USING 'ALLNODES FREELY 


would yield INHERIT. 
Similar to <relation)ING except 
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{relation)ED IN <set) 


FIELDS OF (set) 


KNOWN 


THOSE 


ON PATH <pathoptions) 


that it finds those objects 
operated upon rather than on. 
For example, 


USED FREELY BY ANY CALLING 
GETVALUE 


{set) is a collection of record 
names. The fields of each record 
are to be operated on. 


WHO USES FIELDS OF SLOTRECORD 


This verb implies the set of all 
functions that have been 
analyzed. For example, 


WHO IS KNOWN 


prints out a list of all of the 
functions that have been 
analyzed. 


This command implies the set 
created by the last Masterscope 
command. For example, 


WHO IS USED FREELY BY ASSERTION- 
RESOLVE 
WHO BINDS THOSE 


would find where the specified 
variables are bound. 


This option implies a set 
constructed by the specified 
<pathoptions) (see Chapter 
26.5). For example, 


IS NODE BOUND BY ANY ON PATH TO 
"GETVALUE 


The value of this specification 
is the same as that created by 
SHOW PATHS command with similar 
arguments. . 





es 
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26.4 SPECIFYING RELATIONS 


Relations are comparisons between sets. A relation helps to constrain or identify 
the set of objects to be considered for further analysis. A relation is implemented 


as a verb. Some verbs may accept modifiers. All may be used in the present tense 
or as present or past participles. 


CALL A function <fn1) calls a 
function <fn2) if the definition 
of <fn1) contains one or more of 
the following expressions: 


(<fn2) <arguments)) 
(APPLY <fn2) (arguments) ) 
( FUNCTION «fn2)) 


«—, WHO CALLS WHOM IN (FILEFNSLST 'AMISNET) 


EDIT.SLOT.OR.DEMON--(IS.SLOT.NAME? IS.DEMON.NAME?) 
EXECUTE. UPDATE. FUNCTION--(IS.MODEL.NAME? IS.SLOT.NAME? 
IS.DEMON.NAME?) 

UNLOAD. AND. CLOSE. DATABASE--(CHECK.OPEN. DATABASE 

PRINT .DB.MESSAGE) 

MAKENODE--(ADD.TO.DB.VARS INITIALIZE.NODE) 


etc. 


CALL SOMEHOW A function <fni) calls another 
function <fn2) somehow if there 
is some path from the first 
function to the other. Several 
levels of indirection may be 
necessary to determine if <fn1) 
calls <(fn2). Masterscope 
recomputes this relationship 
dynamically because of the 
amount of information that must 
be retained in order to explore 
the possible paths to other 
functions. 


SET A function sets a variable if 
the function contains one or 
more expressions of the form 
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(SETQ <variable) (expression) ) 
(SETQQ <variable) <expression)) 
(i.e, see Sections 3.8 and 3.9). 


«-. WHO SETS WHOM 

SHOW.DATA.MODEL.OPERATIONS -- (A.DB.NODE) 
INITIALIZE.NEW.DATABASE -- (CURRENT.DATABASE.NAME 
CURRENT.DB.VARS CURRENT.DB.PROPS CURRENT.DB.FNS) 
done 


SMASH A function smashes a variable if 
the function performs a 
destructive replacement of the 
value of that variable. 
Destructive functions include 


(RPLACA <variable) <expression)) 
(RPLACD (variable) <expression) ) 
(DREMOVE ??) 

(SORT ??) 


(i.e., see Section 3.9 and 
consider any destructive 
functions). 


«. WHO IS SMASHED BY WHOM 
MODEL.NAME -- (DELETE.MODEL) 
X -- (REPLACA) 

done 


TEST A variable is tested by a 
function if its value is only 
distinguished between NIL and 
non-NIL values. Testing 
expressions include 


(COND (<variable) ...) 
(AND (variable) ...) 


<, WHO IS TESTED BY WHOM 

CURRENT .DATABASE.NAME -- (MAKEDEMON INHERIT MAKENODE 
EXISTP ADD.TO.DB.VARS OPEN.AND.LOAD.DATABASE 
INITIALIZE.NEW.DATABASE) 

INSTANCE -- (CREATE. INSTANCE) 

SLOTS -- (INITIALIZE.SLOTS) 

etc... 








REFERENCE 


USE 
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A variable is referenced by a 
function if its used in any 
other way than being set. 


If unmodified, a function uses a 
variable if it satisfies any of 
SET, SMASH, TEST, or REFERENCE. 


«. WHO USES A.DB.GRAPH FREELY 
(SHOW.DATA.MODELS SHOW.OPEN.DATABASE.STRUCTURESHOW. 


DATABASE .MODELS) 


«— WHO IS USED FREELY BY ANY CALLING 'EXISTP 


(NODE) 
BIND 


USE AS A FIELD 


FETCH 

REPLACE 

CREATE 

USE AS A RECORD 


USE AS A PROPERTY NAME 


USE AS A CLISP WORD 


A variable is bound by a 
function if it occurs in the 
argument list of the function or 
a PROG expression within the 
function. 


A name is used as a field when 
it occurs as a record field name 
in create, fetch, or replace 
expressions. 


A name appears as a field name 
within a fetch expression. 


A name appears as a field name 
within a replace expression. 


A name appears as a record name 
within a create expression. 


A name is used as a record name 
in create or TYPE? expressions. 


A name is used as a property 
name in one or more property 
list functions. These include 
expressions of the form 


(GETPROP <atom) <name)) 
(PUTPROP <atom) 

<name) expression) ) 
etc. 


A name is either an iterative 
statement operator or a user 
defined CLISP word. 
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CONTAIN Functions, records, and 
variables are contained within 
files. Masterscope computes this 
relation dynamically from File 
Package information. 


DECLARE AS LOCALVAR Variables may be declared as 
DECLARE AS SPECVAR local variables or special 
variables within a function. 


Modifying Verbs 

The verbs USE, SET, SMASH, and REFERENCE may be modified by the ad- 
verbs FREELY and LOCALLY. These adverbs determines whether a variable is 
bound within the stack frame of the function. 


«<—. WHO IS USED LOCALLY 
(TEMP TRUNCATION SIZE CX3 R CX1 CX2 I CX Y X) 


26.5 SPECIFYING PATHS 


A path is a specification through the hierarchy of function calls. SHOW PATHS 
takes a path specification to determine what functions it should identify for you. 
There are several path options that you may specify: 


FROM <set) This option displays all function 
calls from the elements of <set). 


<. SHOW PATHS FROM CDIFFERENCE 
1.CDIFFERENCE COMPLEX 


2s REAL 

es IMAG 

NI 

TO <set) This option displays the function 


calls that lead to elements of (set). 
If TO is given before FROM, the tree 
will be inverted and a warning 
message will be printed. 


When both FROM and TO are specified, 
Masterscope traces the elements of 
the set given by 


CALLED SOMEHOW BY X AND CALLING Y 
SOMEHOW 
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If TO is not specified, the following 
form is assumed: 


TO KNOWN OR NOT @ GETD 
<. SHOW PATHS TO REAL 


(inverted tree) 
1.REAL CPLUS 


a CDIFFERENCE 

3 CMULT 

4. PRINT .COMPLEX 

NIL 

AVOIDING <set) This option does not display any 


function that is an element of (set). 
AMONG is a synonym for AVOIDING NOT. 


«-. SHOW PATHS TO REAL AVOIDING CMULT 
(inverted tree) 
1.REAL CPLUS 


Zi CDIFFERENCE 

Sa PRINT .COMPLEX 

NIL 

NOTRACE <set) This option does not trace any 


element from (set). Functions marked 
NOTRACE are printed in the tree, but 
the tree is not expanded beyond that 
function. 


SEPARATE <set) This option displays a separate tree 
for each element of <set). A tree may 
become very complex when you have 
many layers in the function call 
hierarchy. This makes it difficult to 
comprehend the paths to various 
functions. Judicious use of the 
SEPARATE option will make the 
function hierarchies displayed by 
SHOW PATHS more comprehensible. 


LINELENGTH <n) This option resets the line length of 
the output file before displaying the 
tree. The line length is used to 
determine when the tree should 
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overflow and, therefore, be expanded 
at a lower level. 


26.6 DESCRIBING FUNCTION BEHAVIOR 


The behavior of a function is described by a template. A template is a pattern of 
a function’s evaluation. It is a list consisting of a set of atoms that describe each 
of the arguments to the function. 

Masterscope templates are stored in a hash array whose address is the value 
of MSTEMPLATES. To inspect this array, use EDITV on the value of 


MSTEMPLATES. 


The atoms which may appear in a template are 


PPE 


NIL 


SET 


SMASH 


Indicates a parenthesis error when an 
expression appears in this location. 


CDR (NIL EVAL . PPE) 


means that the CDR is not evaluated, its 
argument is, and nothing more should 
appear in the argument list. 


Indicates that an expression occurring at 
this location is not evaluated. 


GO (NIL NIL . PPE) 


means that neither the GO nor its label 
are evaluated and, moreover, nothing else 
may occur in the expression. 


A variable appearing at this location is 
set by the function. 
SAVESETQ (NIL SET EVAL . PPE) 


means that the first argument is set to 
the value of the second argument which is 
evaluated. 


Indicates that the value of the expression 
appearing at the location is destructively 
modified in place. 


/LCONC (CALL SMASH EVAL . PPE) 


TEST 


RETURN 


EFFECT 


FETCH 


REPLACE 


RECORD 


CREATE 


BIND 
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The expression appearing at this location 
is used as a predicate. The argument at 
this location is not evaluated. 


GO (NIL NIL . PPE) 


means that neither the GO nor its label 
are evaluated and, moreover, nothing else 
may occur in the expression. 


The value of the function is given by the 
value of this expression. 


AND (NIL .. TEST RETURN) 


means that the value of AND is the value 
of its last argument if all of its 
arguments evaluate true. 


The expression appearing at this location 
is evaluated, but its value is not used by 
the function. 


SELECTQ (CALL EVAL .. (NIL .. 
EFFECT RETURN) RETURN) 


means that each expression in the action 
part of a selector is evaluated, but only 
the last action is returned as the value 
of the selector. 

Expressions represented by EFFECT may 
affect other variables; they may be viewed 
as side effects. 


An atom at this location is the name of a 
field that is to be fetched. 


An atom at this location is the name of a 
field that is to be replaced. 


An atom at this location is the name of a 
record. 


An atom at this location is the name of a 
record that is to be created. 


An atom at this location is a variable 
that is bound. 
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PROG (! NIL 
(BOTH 
(.. (IF LISTP 
(NIL EVAL .. 
EFFECT) 
NIL) ) 
(.. (IF LISTP 


(BIND BIND) )) 
.. (IF LISTP EFFECT) ) 


CALL An atom at this location is a function 
that is called. 


ERRORSET (CALL EVALQT .. EVAL) 


Note that functions which have NIL as 
their first atom are executed directly by 
the interpreter, whereas those with CALL 
as their first atom are defined in terms 
of the more primitive functions. 


CLISP An atom at this location is used as a 
CLISP word. 


TESTRETURN A combination of TEST and RETURN. If the 
value of the function is non-NIL, then it 
is returned. For instance, a one-element 
COND clause is analyzed this way. 


OR (NIL .. TESTRETURN RETURN) 


These atoms are supplemented by a set of special forms. Each form is a list 
whose CAR is interpreted according to the above atoms. These forms are 


.. <(template) - When .. appears before a 
part of the template, the 
next element of the 
template may occur an 
indefinite number of times. 


EVAL (CALL EVALQT .. EVAL) 
RESETFORM (CALL .. EVAL) 


PROG1 (NIL RETURN .. EFFECT) 


26.6 Describing Function Behavior 


(BOTH <template) <template)) 


PROG 


(IF <expr) <temp) <temp)) 


EVALA 


(@ <exprform) <tempform) ) 


DECLARE 


(MACRO . <macro)) 
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Indicates that the current 
expression is to be 
analyzed twice using each 
of the templates in turn. 


(NIL 
(BOTH 


(IF LISTP 
(NIL EVAL .. 
EFFECT) NIL) ) 


(IF LISTP (BIND) 
BIND) ) ) 
.. (IF LISTP EFFECT) ) 


The expression is evaluated 
when the function is 
analyzed by Masterscope. If 
the result is non-NIL, use 
the first template to 
analyze the function; 
otherwise, use the second 
template. 


(BOTH (IF & &) (CALL EVALQT 
EVAL . PPE) 


The <exprform) is evaluated 
to produce an expr), and 
the <tempform) is evaluated 
to give a (template), both 
when the function is 
analyzed. The <expr) is 
analyzed using <template). 
This allows you to 
dynamically analyze 
expressions. 

(CALL .. (@ EXPR &)) 

The form <macro) is 
interpreted like a compiler 
macro. The resulting form 
is analyzed. 


964 Masterscope 


RESETVARS MACRO 


Some of the templates may be rather complex. Consider the following exam- 
ples: 


DECLARE (CALL .. 
(@ EXPR 
(CONS NIL 
(SELECTQ (CAR (LISTP EXPR)) 
(LOCALVARS 
(QUOTE (IF LISTP 
(25 
LOCALVARS) 
LOCALVARS) ) ) 
(SPECVARS 
(QUOTE (IF LISTP 
Ce 
SPECVARS) 
SPECVARS) ) ) 
NIL)))) 
SETATOMVAL (CALL (IF (EQ (CAR (LISTP EXPR) ) 
(QUOTE QUOTE) ) 
(NIL SET) 
EVAL) 
EVAL . PPE) 
EVALA (BOTH (IF (EQ (CAR (LISTP (CADDR EXPR))) 
(QUOTE QUOTE) ) 
(NIL NIL (NIL (.. (BIND))))) 
(CALLEVALQT EVAL . PPE)) 
FUNCTION (CALL (REMOTE (IF LITATOM CALL LAMBDA) ) 
(IF LITATOM EVAL NIL)) 
* (! (IF (EQ (CADR EXPR) 
(QUOTE ASSERT: ) ) 
(NIL NIL 
(IF LISTP 


(@ (CDR EXPR) 
(LIST QUOTE ..) 
(MSWORDNAME (CAR 
EXPR) )))))) 
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Masterscope templates are stored in a hash array whose address is stored in 
the variable MSTEMPLATES. You may inspect the individual entries in the 
hash array by performing the following operations (in INTERLISP-D): 


DV [MSTEMPLATES] 


which opens a DEDit window displaying the HARRAYP address. Then, select 
EDITV on the HARRAYP address to open another window displaying the indi- 
vidual entries. 


26.7 MASTERSCOPE FUNCTIONS 


The Masterscope database is updated by many of the INTERLISP subsystems. 
Updating occurs through function calls that add information to or modify infor- 
mation in the database. Several functions allow you to use the Masterscope data- 
base from within your programs. 


26.7.1 Entering Masterscope 


You enter Masterscope from the INTERLISP top-level READ-EVAL-PRINT 
loop by executing MASTERSCOPE, which takes the form 


Function: MASTERSCOPE 

# Arguments: 1 

Argument: 1) a command, COMMAND 

Value: The value returned by executing the 
command. 


If COMMAND is NIL, Masterscope enters into a user executive (see Section 
25.3) through which you may enter commands to be executed. Otherwise, Mas- 
terscope attempts to execute COMMAND and returns the value, if meaningful, 
that is its result. 


+ (MASTERSCOPE) 
Masterscope 4-AUG-83... Type HELP<cr) for command summary. 


A common call to Masterscope is to erase the database when loading a new 
application system. Thus, you might enter the following function call into your 
File Package commands: 


(MASTERSCOPE 'ERASE) 
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26.7.2 Determining Who a Function Calls 
CALLS extracts an analysis of a function from the database. It takes the form 


Function: CALLS 
# Arguments: 2 
Arguments: 1) a function name, FN 
2) a database, USEDATABASE 
Value: As described below. 


CALLS returns a list consisting of four segments of information: 


1. a list of functions called by FN 

2. a list of variables bound in FN 

3. a list of variables used freely in FN 

4. a list of variables used globally in FN. 


FN may be a function name, a definition (for example, a LAMBDA expres- 
sion), or an S-expression. 

If USEDATABASE is non-NIL (usually T), and FN is a function name, 
CALLS uses the Masterscope database. If FN is not a literal atom (e.g., a func- 
tion name) or USEDATABASE is NIL, CALLS performs an analysis of the ex- 
pression. 


+. (CALLS 'MAKESLOT 'T) 

((EQUAL PUTPROP MAPCAR EXISTP ENTER GETPROP 
LIST GIVE.TO.OFFSPRING) 

(INHERITANCE.TYPE METHOD NODE SLOT) 
(XNIL))) 


CALLSCCODE 

An alternative form of CALLS, CALLSCCODE, analyzes compile code (remem- 
ber: we said Masterscope only works on interpreted code). CALLSCCODE ana- 
lyzes compiled code and returns a list consisting of five elements: 


1. a list of functions called via ‘‘linked’’ function calls 
2. a list of functions called regularly 

3. a list of variables bound in FN 

4. a list of variables used freely 

5. a list of variables used globally. 


CALLSCCODE takes the form 
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Function: CALLSCCODE 


# Arguments: 1 
Argument: 1) a function name, FN 
Value: As described above. 


26.7.3 Determining the Free Variables 


You may determine the free variables used within a function by executing 
FREEVARS, which takes the form 


Function: FREEVARS 

# Arguments: 2 

Arguments: 1) a function name, FN 
2) a database, USEDATABASE 

Value: A list of the free variables used within 
FN. 


FN may be a function name, a definition, or a form. If USEDATABASE is 
NIL or FN is an S-expression, FREEVARS performs an analysis of the expres- 
sion to determine the free variables. Otherwise, USEDATABASE is usually T, 
and the free variables are determined from the Masterscope database. In this 
case, if FN has not been previously analyzed, it is now analyzed and the informa- 
tion entered into the Masterscope database. 

Consider the following example: 


«-(FREEVARS 'SHOW.DATA.MODEL) 
(NODE DATABASE.WINDOW A.DB.MODEL A.DB.GRAPH) 


26.7.4 Getting and Setting Templates 


Masterscope uses templates to analyze a function behavior. It knows about 
many of the basic functions provided by INTERLISP. You may obtain a tem- 
plate by executing GETTEMPLATE, which takes the form 


Function: GETTEMPLATE 

# Arguments: 1 

Argument: 1) a function name, FN 

Value: The template used by Masterscope, if 


available. 
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Consider the following examples: 
<—(GETTEMPLATE 'TCONC) 


(SMASH EVAL . PPE) 


<(GETTEMPLATE 'SAVESET) 
((IF 


(EQ (CAR (LISTP EXPR)) (QUOTE QUOTE) ) 
(NIL SET) EVAL) EVAL EVAL EVAL . PPE) 


«-(GETTEMPLATE 'RPTQ) 
(EVAL (BOTH (@ (QUOTE RPTN) (QUOTE BIND)) RETURN) . PPE) 


You may establish a template for a function using SETTEMPLATE, which 
takes the form 


Function: SETTEMPLATE 


# Arguments: 2 
Arguments: 1) a function name, FN 

2) an S-expression, TEMPLATE 
Value: The old template, if any, for FN. 


SETTEMPLATE changes the template for FN in MSTEMPLATES. It re- 
turns the old template, if any. 


26.7.5 Defining Masterscope Synonyms 


Masterscope responds to many different commands. You may define synonyms 
for frequently used commands using SETSYNONYM, which takes the following 
form 


Function: SETSYNONYM 
# Arguments: 2 
Arguments: 1) a new phrase, NEWPHRASE 
2) a meaning for the phrase, MEANING 
Value: NIL. 


Masterscope defines a relationship between NEWPHRASE and MEAN- 
ING. Whenever it sees NEWPHRASE in a command, it substitutes MEANING 
for NEWPHRASE before executing the command. Consider the following ex- 
ample (after the IRM): 
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*<—-(SETSYNONYM 'GLOBALS 
"(VARS IN GLOBALVARS 


OR @(GETPROP X 'GLOBALVAR) ) ) 
NIL 


26.7.6 Parsing a Relation 


Masterscope provides several functions for users who want to write their own 
analysis routines. PARSERELATION creates an internal representation (e.g., a 


subset of the Masterscope database structure) for the given relation. It takes the 
form 


Function: PARSERELATION 

# Arguments: 1 

Argument: 1) a relation, RELATION 
Value: The internal representation. 


Relations are described in Section 26.4. The internal representation re- 
turned by PARSERELATION is not meaningful to you. Usually, you set its 
value to a variable which is later given to GETRELATION. Consider the follow- 
ing example: 


<(PARSERELATION '(USE FREELY) ) 
(TABLES 
(({ HARRAYP }#7,1624 . MSREHASH) 

{ HARRAYP }#7,1020 . MSREHASH) 
( ({ HARRAYP }#1,2574 . MSREHASH) 

{ HARRAYP }#1,2340 . MSREHASH) 
( ({ HARRAYP }#7,1110 . MSREHASH) 

{ HARRAYP }#7,1114 . MSREHASH) 
(({ HARRAYP }#1,2054 . MSREHASH) 

{ HARRAYP }#7,1204 . MSREHASH) ) 


Primitive relations are stored in a pair of hash tables, one for the ‘‘forward”’ 
direction, and one for the “reverse” direction. Hash tables take less storage 
space. Searching is more efficient which means fast access. To retrieve informa- 
tion from the Masterscope database (or a subset of it), Masterscope performs a 
union across the relevant tables as determined by the relation. 


26.7.7 Getting the Results of a Relation 


GETRELATION evaluates an item with respect to the given relation and returns 
the result. In effect, PARSERELATION and GETRELATION allow you to cir- 
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cumvent the analysis of commands which are frequently used by analyzing them 
once. It takes the form 


Function: GETRELATION 
# Arguments: 3 


Arguments: 1) an item, ITEM 
2) a relation, RELATION 
3) an inversion flag, INVERTED 


Value: A list of atoms satisfying the relation. 


RELATION should be an S-expression specifying a relation or an internal 
representation that was previously created by PARSERELATION. If RELA- 
TION is an S-expression, GETRELATION calls PARSERELATION to create 
the corresponding internal representation. 

ITEM is an atom. GETRELATION analyzes ITEM with respect to RELA- 
TION and returns a list of atoms, if any, that satisfy the relationship. Consider 
the following example: 


«(GETRELATION 'SHOW.DATA.MODEL '(USE FREELY) ) 


SLOT - mmoo— GIVE.TO.OFFSPRING DO.SUBNODE 
DO.DEMON 

FROM - Bee ae INHERIT.ALL.SLOTS.OR.DEMONS 
INHERIT .SLOT 

TO - Fe ae INHERIT.ALL.SLOTS.OR.DEMONS 

etc... 


If INVERTED is T, then the sense of the relation is inverted. That is, in- 
stead of determining who SHOW.DATA.MODEL uses freely, GETRELA- 
TION determines who uses SHOW.DATA.MODEL freely. 

If ITEM is NIL, GETRELATION returns a list of atoms which have the 
relation with any other atom, i.e., it answers the question ‘““WHO (relation)S 
ANY”. ; 


27.7.8 Testing a Relation 
TESTRELATION allows you to test if an item has a relation to another item. It 
takes the form 

Function: TESTRELATION 

# Arguments: 4 


Arguments: 1) an item, ITEM 
2) a relation, RELATION 


Value: 
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3) an item to be tested, ITEM2 
4) an inversion flag, INVERTED 


A list of functions satisfying the 
relation, if any. 


TESTRELATION is equivalent to 


(MEMBER ITEM2 


(GETRELATION ITEM RELATION INVERTED) ) 


If ITEM2 is NIL, the function call is equivalent: 


(NOT (NULL (GETRELATION (ITEM RELATION INVERTED) ) ) ) 


i.e., it tests if ITEM has the given relation with any other item. 


26.7.9 Mapping Across a Relation 


MAPRELATION applies a function to every pair of items related via a specified 
relation. It takes the form 


Function: 
# Arguments: 


Arguments: 


Value: 


MAPRELATION 
2 


1) a relation, RELATION 
2) a mapping function, MAPFN 


The result of applying MAPFN to the pairs 
of items. 


26.7.10 Updating the Database 


You may update a function that you have created or modified using UP- 
DATEEN, which takes the form 


Function: 
# Arguments: 
Arguments: 


Value: 


UPDATEFN 
2 


1) a function, FN 
2) an analysis flag, EVENIFVALID 


NIL. 


This function operates like the command ANALYZE (FN). UPDATEFN 
will analyze FN if it has not previously been analyzed or if it has been changed 
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since it was last analyzed. If EVENIFVALID is T, UPDATEFN will reanalyze 
FN even if Masterscope thinks it has a valid analysis in the database. 


*(UPDATEFN 'CMULT T) 


-NIL 


UPDATECHANGED, which takes no arguments, applies UPDATEFN to 
every function which has been marked as changed. It takes the form 


Function: 


# Arguments: 


Arguments: 


Value: 


UPDATECHANGED 
0 

N/A 

NIL. 


MSMARKCHANGED marks a function, FN, as changed and notes that it 
needs to be reanalyzed. It takes the form 


Function: 


# Arguments: 


Arguments: 


Value: 


MSMARKCHANGED 


3 


1) a function, FN 
2) a type, TYPE 
3) a reason code, REASON 


NIL. 


The values of REASON are the same as those used by the function 
MARKASCHANGED (see Section 17.3.9). 


26.7.11 Dumping the Masterscope Database 


DUMPDATABASE dumps the current Masterscope database on the current 
output file in a loadable form. It takes the form 


Function: 


# Arguments: 


Argument: 


Value: 


DUMPDATABASE 

1 

1) a list of functions, FNSLST 
NIL. 


If FNSLST is non-NIL, DUMPDATABASE will only dump the information 
for those functions which appear in FNSLST. 
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+-(DUMPDATABASE 'CMULT) 
(READDATABASE) 
( 


CALL CMULT (COMPLEX DIFFERENCE TIMES REAL IMAG PLUS) NIL 
BIND CMULT NIL NIL 
NLAMBDA CMULT NIL NIL 
NOBIND CMULT NIL NIL 
RECORD CMULT NIL NIL 
CREATE CMULT NIL NIL 
FETCH CMULT NIL NIL 
REPLACE CMULT NIL NIL 
REFFREE CMULT NIL NIL 
REF CMULT (CX1 CX2) NIL 
SETFREE CMULT NIL NIL 
SET CMULT (CX3) NIL 
SMASHFREE CMULT NIL NIL 
SMASH CMULT NIL NIL 
PROP CMULT NIL NIL 

TEST CMULT NIL NIL 
TESTFREE CMULT NIL NIL 
PREDICATE CMULT NIL NIL 
EFFECT CMULT NIL NIL 


) 
NIL 


where the listing provides a description of CMULT from all the possible ways 
Masterscope analyzes a function. 

A variable, DATABASECOMS, is initialized to 

((E (DUMPDATABASE) ) ) 

Thus, you may execute a MAKEFILE as follows: 

(MAKEFILE 'DATABASE. <extension) ) 


to save the current Masterscope database. 


2 





The Record Package 


The Record Package permits you to define data structures whose usage is inde- 
pendent of structural details. You declare the data structures to be used by your 
programs through record declarations. Thereafter, you can manipulate the data 
without concern for the underlying data structures. INTERLISP automatically 
computes the appropriate expressions from the data structure declarations that 
are necessary to accomplish the access and storage operations. You may change 
the data structure merely by changing the declarations. The program automati- 
cally adjusts itself to these new conventions. 


27.1 RECORD DECLARATIONS 


A record declaration specifies the format of a data structure known as a record. 
Each record has a name that identifies the data structure. Each record is com- 
posed of a variable number of fields. The specification of the record’s fields de- 
pends on the type of the record. There are currently ten record types defined by 
INTERLISP. Fields are identified by names. For each field, INTERLISP gener- 
ates the expression necessary to retrieve data from or store data to that field 
when it is referenced by the program. Fields may be further subdivided into sub- 
fields by subdeclarations. In effect, records may recursively contain other record 
declarations. 

The Record Package is implemented via the CLISP and DWIM subsystems. 
Record operations are translated using CLISP declarations. You may declare 
local record declarations to override global ones. 


27.1.1 Components of the Record Declaration 


There are ten record types recognized by the Record Package. A record type 
implicitly specifies how data are accessed or stored within the record (i.e., the 


“data path’’). The record types are given below: 


975 


976 The Record Package 


Record Types 


Record Type Data Structure Supported 
RECORD generic list 
TYPERECORD "typed" list 
DATATYPE user-defined datatypes 
ARRAYRECORD arrays 
ATOMRECORD property list 
PROPRECORD lists with property 
list format 
ASSOCRECORD association lists 
HASHLINK typeless, but hash- 
linked 
ACCESSFNS typeless, but access 


is defined in the 
record declaration 
itself 


The record name is a literal atom that identifies the data structure. The 
record name is used by the Record Package functions, by the File Package, and 
to specify a template for an arbitrary list structure. 

The fields of a record are the description of its structure. Fields may or may 
not have names. Those with names are accessible by the program. NIL is used to 
indicate those fields that the program will not access. This facility allows you to 
apply several different templates to a single data structure. Each template has a 
definition for the fields to be accessed when that template is applied to the data 
structure. This mechanism is not unlike the concept of a “view’’ or a “‘sub- 
schema” that is used in database management systems. The interpretation of 
the ‘‘field’’ component depends on the record type. These interpretations will be 
addressed in the sections describing each record type (see Sections 27.4 through 
27.9). 

Finally, a record declaration may be terminated by a record tail. Record 
tails are optional components of the declaration. The record tail allows the user 
some control over the manner in which certain Record Package functions are 
applied to the record. 

The format for a record declaration is written as follows: 


(record-type record-name fields [record-tail]) 
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27.1.2 Using the Record Declaration 


To use a record structure, you prefix a field name from the record with the name 
of a literal atom whose value is a data structure corresponding to the record type. 
Let us assume we have defined the following record: 


«(RECORD president 
( first.name NIL election.year party votes 


loser.name loser.party . loser.votes) ) 
PRESIDENT 


Note that the period is significant and required before the last field name by 
the declaration. 

Let us further assume that we have two records (note lower case, indicating 
instances of the template): 


(SETQ kennedy 
"(john f 1960 democrat 303 nixon whig 219)) 
(JOHN F 1960 DEMOCRAT 303 NIXON WHIG 219) 


—(SETQ nixon 
"(richard m 1972 republican 521 megovern democrat 17)) 
(RICHARD M 1972 REPUBLICAN 521 MCGOVERN DEMOCRAT 17) 


We can obtain the values of various fields as follows: 


«-kennedy:election.year 
1960 


“nixon: loser.name 
megovern 


When you write a statement of the form “kennedy:election.year’’, you are 
implicitly saying that ‘“‘kennedy”’ is an instance of the record PRESIDENT. The 
interpretation of ‘“‘kennedy:<field name)” depends on the current value of 
KENNEDY. : 

What happens, then, if the underlaying data structure is not equivalent to 
the template that is applied to it? Depending on the operation to be performed, 
you will receive NIL, some unexpected result, or an error message. The Record 
Package does not provide any facilities for run-time validation of data structures 
nor is there any error checking other than that provided by INTERLISP itself. 

We can also use the components of records as arguments to any IN- 


TERLISP function. A ae 
‘“‘Was Kennedy’s margin of victory greater than Nixon s?”’ might be en- 


coded as 
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<— (GREATERP 
(DIFFERENCE kennedy:votes kennedy:loser.votes) 
(DIFFERENCE nixon:votes nixon:loser.votes) ) 
NIL 


Clearly, by inspecting the records above, we see that the answer is false (rep- 
resented by NIL). 

Now, in the record giving information about “‘kennedy’’, we have made a 
slight error. Richard Nixon did not belong to the Whig party, but to the Republi- 
cans. We can replace the value of the field “‘loser.party” in the record ‘‘ken- 
nedy”’ as follows: 


kennedy: loser.party*republican 
which translates to 
(CAR (RPLACA (CADR (CDDDDR kennedy)) 'republican)) 


The value returned from a storage operation is the value that is assigned to the 
field of the record, unless an error occurs. 


27.1.3 Translating the Record Declaration 


The record declaration is translated into a set of record operations that are then 
stored elsewhere by CLISP. For example, the field reference “‘kennedy:elec- 
tion.year’’ is equivalent to 

(CADDR kennedy) 


INTERLISP replaces each access to a record field by an expression of the 
form 


(fetch <field name) of <atom)) 
Thus, we would see ‘‘kennedy:election.year’’ expressed as 
(fetch election.year of kennedy) 


INTERLISP replaces each store to a record field by an expression of the 
form 


(replace <field name) of <atom) by <value)) 
Thus, we would see ‘‘kennedy:loser.party«-republican” expressed as 


(replace loser.party of kennedy by republican) 
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27.1.4 Record Subfields 


As we mentioned above, record declarations may be recursively nested to yield 
subdeclarations of individual fields. In every election, we have one winner, but 
we may have more than one loser (as has happened in several elections). Thus, 
the loser field needs to be replicated to represent this information. We can de- 
scribe this by declaring the loser field to be a RECORD itself. Let us assume 


there are only two losers per election. Then, we can redefine PRESIDENT as 
follows: 


*- (RECORD PRESIDENT 
(first.name NIL election.year party votes . loser) 
(RECORD loser 
(loser.name1 loser.party1 loser.votesi 


loser.name2 loser.party2 . loser.votes2) ) ) 
PRESIDENT 


We might specify the election record for Ronald Reagan as follows: 


(SETQ reagan 
(CREATE presidents 

first.name+ ronald 
election. year+ 1980 
party republican 
votes+-465 
loser.name1¢carter 
loser.party1« democrat 
loser.votes1i«70 
loser.name2« anderson 
loser.party2« independent 
loser. votes2«0) ) 


27.2 CREATING A RECORD 


As we mentioned above, record operations may be applied to any arbitrary data 
structure because the record declaration acts as a template that overlays the data 
structure to define its fields. However, caution should be exercised because a 
mismatch between the template and the actual data structure may result in an 
error. A good policy to follow is to create new instances of records using the 
record declarations that define their access and storage paths. 

To create a new instance of a record, the Record Package provides the CRE- 


ATE expression, which takes the form 


(CREATE record-name . assignments) ) 
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and is usually used in a SETQ statement as follows: 
(SETQ <atom) (CREATE record-name (assignments) ) 


which gives the atom a value consisting of the data structure described by the 
record declaration. INTERLISP initializes the data structure according to the 
specified record type. 

The [assignments] field is optional. It specifies the methods by which indi- 
vidual elements of the data structure are to be initialized. Elements that are not 
specified in [assignments] will be given the default value, if one is specified in the 
record-tail or NIL. 

Expressions in (assignments) may take one of the following forms: 


field-name« S-expression 
The expression initializes the value of the field to the value of the S-expression 
when it is evaluated. 


<(SETQ johnson 
(CREATE presidents 
first-name«lyndon 
election-year+ 1964 
party democrat 
votes*+486) ) 
(lyndon 1964 democrat 486) 


initializes a segment of the record that describes Lyndon Johnson’s election. 


USING S-expressions 

This expression places higher priority on the presence of a default in the record 
tail. For each field name, if there is no value specified in an expression in the 
record tail, then the value defined in the USING expression will be used to ini- 
tialize that field. Let us assume the record declaration 


<-(RECORD state 
(admin.number population . electoral.votes) . 
electoral.votes+3) 

STATE 


which defines ‘‘state” as a record. The record tail specifies that each state has at 
least three electoral votes: two senators and at least one representative. Let us 
create a specific state: 


<—(SETQ california 
(CREATE state 
admin.number*¢ 18 
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USING (19953134 45))) 
(18 19953134 45) 


which is translated as 


(LIST 18 (CADR '(19953134 45)) (CADDR '(19953134 45))) 


We could also set the S-expression as the value of an atom and place the 
atom’s name in the USING expression as follows: 


+(SETQ newdata '(19953134 45)) 
(19954134 45) 


<—(SETQ california 
(CREATE state admin.number+-18 USING newdata) ) 
(18 19953134 45) 


In either case, because we have explicitly specified ‘‘tadmin.number’’, the 
value is taken from the CREATE expression. However, the value of ‘‘elec- 
toral.votes’’ remains 3 because there is a default specified in the record tail. 


COPYING S-expressions 

This expression is like USING except that the corresponding values are copied 
from the S-expression using COPY ALL (see Section 6.4.2). The example above 
would translate as follows: 


<(SETQ california 
(CREATE state 
admin.number+18 
COPYING newdata) ) 
(18 19953134 45) 


becomes 


(LIST 18 (COPYALL (CADR newdata) ) (COPYALL (CADDR 
newdata) ) ) 


REUSING S-expressions . 
This expression is like USING except that, wherever possible, the corresponding 


structure in the S-expression is used: 


«(SETQ ca 
(CREATE state 
admin.number+ 18 
REUSING newdata) ) 
(18 19953134 45) 
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The difference between USING and REUSING is that CREATE will at- 
tempt to incorporate as much of the old data structure into the new data struc- 
ture being created. The USING clause creates an entirely new data structure. 


SMASHING S-expressions 
This expression does not create a new instance of the record; rather, it uses the 


value of the S-expression and overlays the record structure on the S-expression 
itself. 


The Definition of CREATE 2 

CREATE is not defined as a function. Rather, DWIM recognizes CREATE as a 
keyword and calls a Record Package function with the entire CREATE expres- 
sion as an argument. The definition of CREATE is found by 


<-(GETPROPLIST 'CREATE) 
(CLISPWORD (RECORDTRAN . create) ) 


The translation of CREATE is found by 


<(DWIMIFY '(CREATE STATE USING NEWDATA) ) 
(CONS (CAR NEWDATA) 
(CONS (CAR (CDR NEWDATA) ) 
(CDR (CDR NEWDATA)))) 


27.3 TESTING FOR RECORDS 


Record templates cannot be applied indiscriminately to any data structure be- 
cause an error may result. Thus, INTERLISP provides a facility for testing to see 
if a data structure “‘looks like’’ an instance of a particular record. 

To test for a record, you use the TYPE? expression, which takes the follow- 
ing form: 


(TYPE? record-name S-expression) 


where it attempts to determine if the S-expression has the same form as record 
name. TYPE? performs differently according to the record type it is checking: 


DATATYPE 
TYPE? returns non-NIL if and only if the S-expression is an instance of the 
record name; type checking is exact. 


TYPERECORD 

TYPE? checks to see that the S-expression is a list beginning with record name. 
Note that TYPERECORDs are identified in their data structure by the name of 
the record declaration. 
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ARRAYRECORD 
TYPE? checks to see that the S-expression is an array with the correct size. 


PROPRECORD 


TYPE? checks to see that the S-expression is a property list with property names 
chosen from those specified in the field component of the record declaration. 


ASSOCRECORD 
TYPE? checks to see that the S-expression is an association list with property 
names chosen from the field component of the record declaration. 

TYPE? may not be applied to record instances of the types RECORD, AC- 
CESSFNS, or HASHLINK. In each case, it will produce the error message 
TYPE? NOT IMPLEMENTED FOR THIS RECORD. 


In Chapter 11, we defined a new record type, COMPLEX. We may see how 
TYPE? is used as follows: 


+(SETQ CX1 (COMPLEX 1.0 3.0)) 
(C20 + 30) 


«- (TYPE? COMPLEX CX1) 


T 

<(SETQ CX2 '(1.0 . 3.0)) 
(1.0 . 3.0) 

(TYPE? COMPLEX CX2) 
NIL 


The Translation of TYPE? 
The translation of TYPE? is found by 


«(DWIMIFY '(TYPE? COMPLEX CX1) ) 
(TYPENAMEP CX1 (QUOTE COMPLEX) ) 


27.4 MANIPULATING RECORD FIELDS 


You may wish to manipulate the values of the fields of a particular record. The 
WITH construct may be used to manipulate record fields as if they were vari- 
ables. It takes the form 


(WITH record-name record-instance {form1) ... <formN)) 


where RECORD-NAME is the name of the record and RECORD-INSTANCE is 
an expression evaluating to a specific instance of that record. The forms are 
evaluated so that references to variables which are actually field names of the 
record are treated via FETCH and REPLACE. 


984 The Record Package 


*-(RECORD RECN (FLD1 . FLD2)) 
RECN 


<(SETQ DATA (LIST 10 20)) 
(10 20) 


+ (SETQ INSTANCE 
(CREATE RECN USING DATA)) 
(10 20) 


«-(WITH RECN INSTANCE (SETQ FLD2 (PLUS FLD1 FLD2))) 
NON-NUMERIC ARG 
(20) 


because the translation is not done properly (although the IRM claims other- 
wise!). 
The translation of this form is 


<— (DWIMIFY 
'(WITH RECN INSTANCE (SETQ FLD2 (PLUS FLD1 FLD2)))) 
(CDR (RPLACD INSTANCE (PLUS (CAR INSTANCE) 
(CDR INSTANCE) ) )) 


However, the following expression will operate correctly: 


«(WITH RECN INSTANCE (SETQ FLD2 (PLUS FLD1 30))) 
40 


< INSTANCE 
(10 . 40) 


but the correction for the problem above is merely to preface the field with the 
record name as follows: 


<-(WITH RECN INSTANCE (SETQ FLD2 (PLUS FLD1 
INSTANCE: FLD2) ) ) 
50 


< INSTANCE 
(10 . 50) 


whose translation is still the same as given above. 


27.5 RECORDS AND TYPED RECORDS 


The Record Package provides two record types for declaring list structures: RE- 
CORD and TYPERECORD. The only difference between these two data struc- 
tures is that typed records have the record name inserted as the first element. 
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We have already seen how the RECORD declaration works in the examples 
given in Section 27.1. Let us examine another example very briefly. Consider the 
record named ADMINISTRATION which is declared as follows: 


«(RECORD administration 


(president-name inaugural-date . vice-president) ) 
ADMINISTRATION 


For both RECORDs and TYPERECORDs, the field descriptions are in- 
cluded within a single list. Let us create an instance of an ADMINISTRATION: 


<—(SETQ admin-1 
(CREATE administration 
( president-name* washington 
inaugural-date+ 04/30/1789 
vice-president adams) ) ) 
(WASHINGTON 04/30/1789 ADAMS). 


while, for a TYPERECORD declaration, it would appear as 
(ADMINISTRATION WASHINGTON 04/30/1789 ADAMS) 


The translation of the access and storage operations takes the additional 
field into account, as follows: 


< ADMIN-1: INAUGURAL-DATE 
04/30/1789 


would be translated as (CADR admin-1) for a RECORD declaration; it would be 
translated as (CADDR admin-1) for a TYPERECORD declaration. 

Within a field specification, NIL may appear as a placeholder to indicate 
fields that you do not wish to reference through this declaration. We could de- 
scribe the PRESIDENT record as follows: 


«(RECORD president 
(birth-date death-date NIL spouse . state)) 


PRESIDENT 


An actual instance of PRESIDENT (for Gerald Ford) might look something 
like 


<(SETQ ford Ree 
(07/14/1913 NIL republican elizabeth michigan) ) 
(07/14/1913 NIL REPUBLICAN ELIZABETH MICHIGAN) 
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The field that we cannot access in this data structure is the name of Ford’s 
party (i.e., Republican). 

In any type of record declaration, NIL is used to indicate a ‘‘don’t care” 
field. If several such fields occur consecutively, you may use an integer in the 
field description to indicate the number of consecutive NILs. 


27.6 PROPERTY AND ASSOCIATION LIST RECORDS 


A PROPRECORD has the format of a property list. FIELDS is a list of property 
names. The field names and their values are stored in a property list format: 


| (<fieldname) <value) ... <fieldname) <value)) 


Field values are accessed via LISTGET and stored via LISTPUT (see Sec- 
tion 6.11). 

When you create a PROPRECORD, only the fields that are actually named 
in the CREATE expression are stored in the list that represents the record. How- 
ever, if you execute a CREATE expression with just the record name, the list 
representation consists of the first field name with a value of NIL. 

An ASSOCRECORD is a record whose entries are stored in association list 
format. FIELDS is a list of literal atoms. The field names and their values are 
stored as follows: 


((<fieldname) . <value)) ... (<fieldname) . <value))) 


Accessing fields is performed via ASSOC while storing values into fields is 
performed via PUTASSOC. 

Consider the following definitions (e.g., relations) which correspond to 
those often used in relational database examples: 


«(PROPRECORD EMPLOYEE (EMPNAME AGE SALARY DEPNAME 
MANAGER) ) EMPLOYEE 


«-(PROPRECORD DEPARTMENT (DEPNAME FLOOR SALES DEPNO) ) . 
DEPARTMENT 


We create an instance of a PROPRECORD using the CREATE expression: 


<— (CREATE EMPLOYEE EMPNAME<¢ 'SMITH 

AGE 30 

SALARY + 25000 

DEPNAME< 'TOYS 

MANAGER* ' JONES) 
(EMPNAME SMITH AGE 30 SALARY 25000 DEPNAME TOYS MANAGER 
JONES) 
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«(CREATE DEPARTMENT DEPNAME< ' TOYS) 
(DEPNAME TOYS) 


We can use an ASSOCRECORD to store information from a dictionary. 
Consider the following definition: 


*-(ASSOCRECORD DICTIONARY 


(POS LABEL DEFINITIONS ETYMOLOGY 
SYNONYMS) ) 
DICTIONARY 


“—(SETQ JUNK 
(CREATE DICTIONARY 
POS+ 'NOUN 
DEFINITIONS«-"'1.0 Scrapped Materials 
2.0 Chinese flat-bottomed 
ship" 

ETYMOLOGY '(PORTUGUESE JUNCO) )) 
((POS . NOUN) 
(DEFINITIONS . ''1.0 Scrapped materials 

2.0 Chinese flat-bottomed ship") 

(ETYMOLOGY PORTUGUESE JUNCO) ) 


JUNK: POS 
NOUN 


27.7 ARRAY AND HASHLINK RECORDS 


An ARRAYRECORD associates field names with array elements. FIELDS is a 
list of atoms that are associated with the corresponding array elements. AR- 
RAYRECORD only creates an array of pointers. Arrays of other datatypes must 
be created using ACCESSFNS which you write. 

A HASHLINK sets up a record of hash arrays. FIELDS may take one of two 
values: 


1. An atom, or 
2. An S-expression having the following form: 


(<fieldname) (arrayname) <arraysize)) 
The <arrayname) indicates a hash array to be used. If it is not given, 
SYSHASHARRAY will be used (see Section 11.3). The <arraysize) is used to 
initialize the hash array if it has not previously been initialized. When the Re- 


cord Package creates a hash array, it initializes via 


(LIST (HARRAY (OR <arraysize) 100))) 
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An ARRAYBLOCK is a record of arrays. Its declaration form is similar to 
DATATYPE as described below. ARRAYBLOCK records are not supported in 
INTERLISP-D. 


27.8 USER DATATYPE RECORDS 


You may create new datatypes by declaring them to be records of the DATA- 
TYPE. FIELDS takes the form 


(<fieldname) . <fieldtype)), or 
«fieldname) 


If <fieldtype) is omitted, the Record Package assumes a default type of 
POINTER. 

The Record Package currently accepts the following specifications for 
<fieldtype): 


POINTER The field contains a pointer to any 
arbitrary INTERLISP object. 
BITS <n) The field contains an (n)-bit 


unsigned integer. 


BETWEEN <ni) <n2) The field may contain an integer that 
lies in the range [{n1) <n2)]. That 
is, an integer, X, obeys the 
expression ni <= X <= n2 


INTEGER The field contains a full-word signed 
FIXP integer. Note that the size of 
the word is machine-dependent. 


FLOATING The field contains a floating point 
FLOATP number. 
FLAG The field contains a one-bit field 


which indicates T or NIL. 


User datatypes are created by executing an expression with DECLAREDA- 
TATYPE (see Section 27.12). 


27.9 ACCESS FUNCTION RECORDS 


An ACCESSENS record is a record for which you may specify both an access and 
a storage function. INTERLISP captures the notion of access-oriented program- 
ming with this record type. 
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FIELDS is a list of entries of the form 
(<fieldname) <access-definition) <¢ store-definition) ) 


where, for each field name, you specify both an access and a storage description. 
These descriptions are usually function calls. The access function is a function of 
one argument, DATUM. It should return a value based on the value of DA- 
TUM. The storage function is a function of two arguments, DATUM and NEW- 
VALUE. It should store NEWVALUE into DATUM and return NEWVALUE, 
if successful, as its value. If the storage definition is NIL or undefined, you will 
not be allowed to store data into the record field. 
Consider the following example (after the IRM): 


+ (ACCESSFNS 
((FIRSTCHAR (NTHCHAR DATUM 1) 
(RPLSTRING DATUM 1 NEWVALUE) ) 
(RESTCHARS (SUBSTRING DATUM 2)))) 
NIL 


«(DWIMIFY '(REPLACE FIRSTCHAR OF X WITH Y)) 
(RPLSTRING X 1 Y) 


Since no storage definition is given for the RESTCHARs field, attempting to 
perform a replacement here would cause an error: 


<(DWIMIFY '(REPLACE RESTCHARS OF X WITH Y)) 
REPLACE not defined for this field 
at RESTCHARS in (REPLACE RESCHARS OF X --) 


Note that ACCESSFNS do not have a CREATE definition. You may specify 
one by the appropriate expression in the record tail. 

The ACCESSENS feature allows you to create data structures which cannot 
be specified by one of the other record types. 


27.10 ATOM RECORDS 


An ATOMRECORD returns an atom created by GENSYM (see Section 9.2.1) 
whose value is the record structure. FIELDS is a list of property names associ- 
ated with an atom. Accessing is performed via GETPROP while storing is per- 
formed with PUTPROP. Consider the following example: 


«-(ATOMRECORD EMPLOYEE (ENAME AGE SALARY DNAME) ) 
EMPLOYEE 


<(SETQ EMPNO-1 
(CREATE EMPLOYEE ENAME< 'SMITH 
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AGE 46 
SALARAY 22000) ) 
A0010 


«-(GETPROPLIST 'EMPNO-1) 
(SALARY 22000 AGE 46 ENAME SMITH) 


27.11 RECORD PACKAGE FUNCTIONS 


The Record Package allows you to edit and manipulate record declarations from 
within programs. These functions are described in this section. 


27.11.1 Editing a Record Declaration 
EDITREC allows you to edit a global record declaration. It takes the form 


Function: EDITREC 
# Arguments: 1-N 
Arguments: 1) a record name, RECORDNAME 
2-N) optional editor commands, COM[1] 
COM[N] 
Value: The name of the record. 


EDITREC is an NLAMBDA, nospread function. It invokes the editor on a 
copy of all declarations in which (CAR EDITRECX) is the record name or field 
name. When you exit the editor, all declarations that have been changed will be 
redeclared. All records that have been deleted will be undeclared. If (CAR 
EDITRECX) is NIL, all declarations will be edited. 


27.11.2 Obtaining a Record Declaration 


RECLOOK allows you to obtain the declaration for a given record name. It 
takes the form 


Function: RECLOOK 

# Arguments: 1 

Arguments: 1) a record name, RECORDNAME 
Value: The declaration for the record. 


If RECORDNAME does not correspond to an existing declaration, REC- 
LOOK returns NIL. 
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<-(RECLOOK 'POSITION) 
(RECORD POSITION (XCOORD YCOORD) 
(TYPE? 
(AND (LISTP DATUM) ) 
(NUMBERP (CAR DATUM) ) 
(NUMBERP (CDR DATUM)))) 


*-(RECLOOK 'REGION) 
(RECORD REGION (LEFT BOTTOM WIDTH HEIGHT) 
LEFT -16383 
BOTTOM*- -16383 
WIDTH* 32767 
HEIGHT*- 32767 


(ACCESFNS 
( (TOP 
(IPLUS 
(fetch (REGION BOTTOM) of DATUM) 
(fetch (REGION HEIGHT) of DATUM) 
-1)) 
(PTOP 
(IPLUS 
(fetch (REHION BOTTOM) of DATUM) 
(fetch (REGION HEIGHT) of DATUM) )) 
(RIGHT 
(IPLUS 
(fetch (REGION LEFT) of DATUM) 
(fetch (REGION WIDTH) of DATUM) 
-1)) 
(PRIGHT 
(IPLUS 
(fetch (REGION LEFT) of DATUM) 
(fetch (REGION WIDTH) of DATUM) )))) 
(TYPE? 


(AND (EQLENGTH DATUM 4) 
(EVERY DATUM (FUNCTION FIXP))))) 


where both examples are taken from the Fugue release of INTERLISP-D. 


27.11.3 Obtaining the Declarations of a Field 


A field name may be used in many different record declarations. When you do 
so, you should ensure that the same semantics are attached to the field name in 
every instance. With this assumption in mind, FIELDLOOK returns a list of all 
declarations in which its argument is represented. Its single argument, 
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FIELDNAME, is the name of a field in zero or more declarations. It takes the 
form 


Function: FIELDLOOK 

# Arguments: 1 

Arguments: 1) a field name, FIELDNAME 

Value: The list of declaration in which FIELDNAME 


is the name of a FIELD. 
Consider the following example: 


«-(FIELDLOOK 'REAL) 
((DATATYPE COMPLEX ((REAL FLOATP) (IMAG FLOATP)))) 


27.11.4 Obtaining a Declaration’s Field Names 


Most records are declared global to the entire program, but declared in only one 
file that comprises the program. It may be necessary in other functions to know 
the names of the fields of a record. RECORDFIELDNAMES returns the names 
of the fields of a given record declaration. It takes the form 


Function: RECORDFIELDNAMES 

# Arguments: 1 

Arguments: 1) a record name, RECORDNAME 

Value: A list of the fields declared for the 
record. 


Consider the following example: 


«-(RECORDFIELDNAMES 'PRES IDENT) 

(LOSER.VOTES2 %. LOSER.PARTY2 LOSER.NAME2 LOSER. VOTES1 
LOSER.PARTY1 LOSER.NAME1 LOSER %. VOTES PARTY 
ELECTION. YEAR FIRST.NAME) 


Note that the value returned does not distinguish between the fields of s 
subrecord and the primary fields of the record itself. 


27.11.5 Accessing or Replacing a Record Value 


RECORDACCESS allows you to access or replace a record value from within a 
function based on the name of the field. This facility is used when you do not 
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know the name of the field in advance, as when you ask the user to specify the 
field. It takes the form 


Function: RECORDACCESS 
# Arguments: 5 


Arguments: 1) a field name, FIELD 
2) an old value, VALUE 
3) an access mathod, TYPE 
4) a new value, NEW 
5) an (optional) declaration, DECL 


Value: The new value. 
TYPE is one of the following methods: 


FETCH or fetch 
FFETCH or ffetch 
REPLACE or replace 
FREPLACE or freplace 
/REPLACE or /replace 


If TYPE is NIL, a default method of FETCH is assumed. Consider the fol- 
lowing definition for COMPLEX (see Chapter 11): 


«(PP COMPLEX) 
(LAMBDA (R I) 
(PROG (TEMP) 
(SETQ TEMP (CREATE COMPLEX) ) 
(RECORDACCESS (QUOTE REAL) 
TEMP NIL (QUOTE REPLACE) 
R) 
(RECORDACCESS (QUOTE IMAG) 
TEMP NIL (QUOTE REPLACE) 
T) 
(RETURN TEMP) )) 


27.12 USER DEFINED DATATYPES 


You may define new datatypes using DECLAREDATATYPE. This function al- 
lows you to define entirely new classes of objects, with a fixed number of fields 
specified by the definition of the data type. Additional functions allow you to 
define the name and type of fields for a given class, to create instances of objects 
of a given class, to access and replace the contents of individual fields within an 
object instance, and to interrogate objects about their contents. 


994 The Record Package 


27.12.1 Defining New Datatypes 


You may define a new datatype using DECLAREDATATYPE, which takes the 
form 


Function: — DECLAREDATATYPE 
# Arguments: 2 | 
Arguments: 1) a datatype name, TYPENAME 
2) a field specification, FIELDS 
Value: A list of field descriptors that 


correspond to the elements of FIELDS. 
TYPENAME is a literal atom which is the name of the new datatype. It may 
not conflict with existing datatypes defined by INTERLISP or the user. 
FIELDS is a list of field specifications that describe the objects that are in- 
stances of the datatype. Each field specification takes the form 
(<fieldname) . <«fieldtype)) 


The permissible field types are 


POINTER The field may contain a pointer to an 
INTERLISP object. 

FIXP The field contains an integer. 

FLOATP The field contains a floating point 
number. 

(BITS <n)) The field contains a non-negative 


integer less than 2**N. 


If FIELDS is NIL, TYPENAME is undeclared. 

If TYPENAME is already declared, it will be redefined. That is, the data- 
type will be redeclared by INTERLISP. This permits you to redefine even the 
basic objects of INTERLISP. However, using this facility is not recommended as 
large parts of INTERLISP will either cease to work or work in strange ways. 
Moreover, the resulting code that you produce is not transportable to other sys- 
tems. 

Printing new datatypes may be difficult. However, using DEFPRINT (see 
Section 15.1.5), you may define one or more functions that print the structure of 
the datatype. You may also define how the objects are to be evaluated using the 
function DEFEVAL. 
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27.12.2 Fetching the Contents of an Object Field 


Individual fields of an object may be fetched (or retrieved) using FETCHFIELD, 
which takes the form 


Function: FETCHFIELD 

# Arguments: 2 

Arguments: 1) a field descriptor, DESCRIPTOR 
2) an object, DATUM 

Value: The contents of the field. 


DESCRIPTOR is a field descriptor returned that is returned by DECLARE- 
DATATYPE. FETCHFIELD returns the contents of the field specified by DE- 
SCRIPTOR. 

If the object is not an instance of the datatype for which DESCRIPTOR is a 
field descriptor, INTERLISP causes an error ‘DATUM OF INCORRECT 
TYPE’. 


27.12.3 Replacing the Contents of an Object Field 


You may replace (or store into) the field of an object using REPLACEFIELD, 
which takes the form 


Function: REPLACEFIELD 
# Arguments: 3 


Arguments: 1) a field descriptor, DESCRIPTOR 
2) an object, DATUM 
3) a new value, NEWVALUE 


Value: The new value. 


DESCRIPTOR is a field descriptor that is returned by DECLAREDATA- 
TYPE. REPLACEFIELD stores NEWVALUE as the contents of the specified 


field into the object. ' . 
If DATUM is not an instance of the object for which DESCRIPTOR is a 


field descriptor, INTERLISP causes an error “DATUM OF INCORRECT 
TYPE". 


27.12.4 Creating an Instance of an Object 


You may create an instance of an object using NCREATE, which takes the form 


996 The Record Package 


Function: NCREATE 
# Arguments: 2 
Arguments: 1) an object name, TYPENAME 
2) a source object, FROM 
Value: The address of the new object. 


NCREATE creates an instance of the specified object by allocating storage 
in memory for the instance. 

If FROM is an instance of TYPENAME, the fields of the new object are 
initialized using the values of the corresponding fields in FROM. 

NCREATE does not work for built-in datatypes such as ARRAYP, 
STRINGP, etc., because they have their own creation and initialization func- 
tions built into the INTERLISP virtual machine. INTERLISP will cause the er- 
ror “ILLEGAL DATA TYPE” if TYPENAME is not a declared datatype. 


27.12.5 Obtaining the Field Specifications 


You may obtain the field specifications for a datatype using the function GET- 
FIELDSPECS. It takes the form | 


Function: GETFIELDSPECS 

# Arguments: 1 

Arguments: 1) an object name, TYPENAME 

Value: A list which is EQUAL to the FIELDS 


argument given to DECLAREDATATYPE. 


GETFIELDSPECS returns a list of the field specifications for the specified 
object. If TYPENAME is not a currently declared object, it returns NIL. This 
allows you to dynamically declare objects by loading files containing the object 
declarations. 


27.12.6 Obtaining the Field Descriptors 
You may obtain the field descriptors of an object using GETDESCRIPTORS, 
which takes the form 

Function: GETDESCRIPTORS 

# Arguments: 1 . 

Arguments: 1) an object name, TYPENAME 

Value: A list of field descriptors. 
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GETDESCRIPTORS returns a list of field descriptors which is EQUAL to 
the value returned by DECLAREDATATYPE. Elements of this list may be used 
in FETCHFIELD and REPLACEFIELD. 


If TYPENAME is not a currently declared datatype, GETDESCRIPTORS 
returns NIL. 


27.12.7 Identifying User Datatypes 


You may determine which datatypes have been defined by a user using USER- 
DATATYPES, which takes the form 


Function: USERDATATYPES 

# Arguments: 0 

Arguments: N/A 

Value: A list of the names of all currently 


declared user datatypes. 


28 





The History Package 


The History Package is a set of commands and functions that allow you to refer 
to what you have done in the past. The primary motivation for the History Pack- 
age is to provide a means whereby you may correct erroneous expressions and re- 
execute them. Each input that you type in is treated as an event. Associated with 
each event is a history list which maintains information relevant to the event. 
Entries on the history list consist of an input and its value. In addition, optional 
information such as side effects and formatting parameters may also be included 
on the history list. 

INTERLISP maintains a list of events. As new events occur, existing events 
are aged. The “‘oldest”’ event is forgotten as each new event is entered onto the 
list. INTERLISP typically remembers about thirty events at one time although 
you may change this value via CHANGESLICE (see Section 28.6.6). 

INTERLISP numbers events for future reference by printing an integer 
number when it is ready to receive the next input in the READ-EVAL-PRINT 
loop. These prompts run from 1 to 100 whence they roll over to 1 again. You may 
reference events by their numbers in history commands. 

When the History Package is activated, each input that you type is placed on 
the history list after it is read, but before it is evaluated. Thus, if the command 
fails, the input expression is available for modification and eventual re-execu- 
tion. In conjunction with the Programmer’s Assistant (see Chapter 25), new 
functions and variables are noted and added to the spelling list. After a function 
or command is executed, its value is also saved on the history list for possible 


referral at a later time. 


28.1 STRUCTURE OF THE HISTORY LIST 


A history list has the following structure: 
(alist event# size max-eventi#) 


999 
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where: alist is a list of events with the 
most recent event first (i.e. at 
the front of the list) 


event# is the event number of the most 
recent event 


size is the maximum number of events 
to be retained 


max-event# is the highest possible event 
number in multiples of 100. 


INTERLISP maintains three history lists: LISPXHISTORY, AR- 
CHIVELST, and EDITHISTORY. LISPXHISTORY records events associated 
with input typed to the READ-EVAL-PRINT loop while EDITHISTORY pre- 
serves your interactions with the INTERLISP Editor. Both are initialized to 
(NIL 0 30 100). ARCHIVELST is used to archive events when you type the com- 
mand ARCHIVE. 

You may disable the recording and maintaining of the history list for either 
the top-level interface or the Editor by setting LISPXHISTORY or EDITHIS- 
TORY to NIL, respectively. 

Each history list has a maximum length—its time slice. As new events occur, 
they are placed at the front of the history list. That is, the history list is treated as 
a FIFO (first-in first-out) queue. The position of an event in the history list corre- 
sponds to its age. So, as new events are entered into the history list, older events 
recede into the past until they reach the threshold of the number of events to be 
remembered. When the numbers of events exceeds this threshold, the oldest 
events are forgotten. The amount of memory consumed in representing a history 
list can be enormous as demonstrated by a simple event below. You may selec- 
tively remember important events using the NAME and RETRIEVE commands 
(see Section 28.4.8). 


Event Structure 
An event, when it is recorded on a history list, has the form 


(<input) <identifier) <value) . <properties)) 


where: « input) is the expression typed in 


<identifier) is the prompt character (which 
helps to identify the subsystem 
you are executing under) 


<{value) is the value of the expression 
after it has been evaluated 


<properties) is a property list 
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The property list of an event is used to store additional information about the 
event. The History Package supports the following properties: 


SIDE 


*ARCHIVE* 


*GROUP* 


*HISTORY* 


*PRINT* 


USE-ARGS 


. -ARGS 


*ERROR* 


*CONTEXT* 
*LISPXPRINT* 


The side effects associated with the 
event. 


Forces an event to be archived when 
it is about to be forgotten, i.e., 
when it is about to fall off the end 
of the history list. 


Used to support execution of a 
previous event. 


Stores a history command that was 
applied to a previous event. 


Used for displaying the event, 
primarily by the Break Package and 
the ?? command. 


Contains arguments for a history 
command. 


Contains the expression for a history 
command. 


Contains information saved when an 
error occurs. 


Used in error processing. 


Stores information for calls to 
Programmer's Assistant functions. 


Let us assume that I have just initialized an INTERLISP session and asked 
INTERLISP to load a file. The script that I would see at the terminal would 


appear as 


Good Evening 


2+-(LOAD 'COMPLEX) 
{KAISLER) COMPLEX. .6 


File Created 22-Nov-84 10:30 


COMPLEXCOMS 


3<-(EDITV LISPXHISTORY) 


To inspect the internals of LISPXHISTORY, you should apply the Editor to 
it to descend into the various levels. Be careful not to modify the history list or 
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you may not be able to undo erroneous events. We may apply Editor commands 
to navigate about the history list: 


1*P 
((& & &) 3 30 100) 

1*1 P 

((& _) (& _ <KAISLER)COMPLEX..6 *LISPXPRINTX & SIDE &) (& 
_ T SIDE & *LISPXPRINT* &)) 


2%*1 P 

((&) _) 

2%*1 P 

((EDITV LISPXHISTORY) ) 

2%*0 02 P 

((&) — <«KAISLER)COMPLEX..6 *LISPXPRINT* ("  & "FTLE 
CREATED " "21-NOV-84 20:27:17" " ' &) SIDE (-1& &€&&E 
SS SRREE EEE EE &-=-)) 

2*PP 


(((LOAD (QUOTE COMPLEX) )) _ <KAISLER)COMPLEX. .6 
*LISPXPRINT* 
('' '" (PRINT <(KAISLER)COMPLEX..6 T) "FILE CREATED "' 
"21-NOV-84 20:27:17" " '" (PRINT COMPLEXCOMS T T)) 
SIDE 
(-1 (/SETTOPVAL CHANGEDFNSLST 
(FACTORIAL PRINT.ARRAY TRUNCATE 
RECIPROCATE 
ROUNDED SIGN ROUNDTO FLOOR 
PRINT.COMPLEX CMULT CZERO 
CDIFFERENCE CPLUS IMAG REAL 
COMPLEX) ) 
(/SETTOPVAL CHANGEDRECORDLST (COMPLEX) ) 
(/SETTOPVAL CHANGEDVARLST (COMPLEXVARS COMPLEXFNS 
COMPLEXCOMS) ) 


(/SETTOPVAL CHANGEDFNSLST 
(FACTORIAL PRINT.ARRAY TRUNCATE 
RECIPROCATE 

ROUNDED SIGN ROUNDTO FLOOR 
PRINT.COMPLEX CMULT CZERO 
CDIFFERENCE CPLUS IMAG REAL 
COMPLEX) ) 

(/SETTOPVAL CHANGEDRECORDLST (COMPLEX) ) 

(/SETTOPVAL CHANGEDVARLST (COMPLEXVARS COMPLEXFNS 

COMPLEXCOMS) ) 

(/SETTOPVAL FILELST NIL) 

(/RPLACD ((COMPLEXCOMS . T)) 

NIL) 


EE 
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(/RPLACA 
((("21-Nov-84 20:27:17" . (KAISLER)COMPLEX. .6) ) 
FILEMAP 
--. (rest of the filemap) ...)) 
(/PUT-1 COMPLEX (FILE ((COMPLEXCOMS . T)))) 
(/SETTOPVAL LOADEDFILELST NIL) 
(/PUT-1 COMPLEX ( FILEMAP «KAISLER) COMPLEX. .6 
.-. (rest of the filemap) ...)) 
-o. (more) ... 


You can see that a considerable amount of information must be stored in 
order to be able to undo events at a later date. 


28.2 UPDATING THE HISTORY LIST 


The history list is updated through the auspices of LISPX (see Section 25.2) 
which functions as an EVAL-PRINT mechanism. When LISPX is given a value, 
it calls HISTORYSAVE to create a new event except for certain commands that 
are executed immediately. HISTORYSAVE (see Section 28.6.1) returns a tem- 
plate of the new event which is bound to LISPXHIST. When LISPX completes 
the evaluation of the input, it stores its value in LISPXHIST (as its CADDR). 
LISPXHIST also provides access to the properties associated with the current 
event. 


28.3 EVENT SPECIFICATION 


Events are associated with user inputs. The key to successful use of the History 
Package is to describe the event which you want to reference. 

An event specification is a statement that describes a sequence of one or 
more events for a history command. A specification is drawn from the following 
set of phrases: 


FROM <1) THRU <2) Specifies the sequence of events 
beginning at address <1) up to 
and including address (2). 
Address <1) may be more recent 
than address <2) thus providing 
for the processing of events in 
reverse order. 


FROM <1) TO <2) Specifies the sequence of events 
beginning at address (1) up to 
but not including address <2). 
Reverse order is allowed. 


FROM <1) Equivalent to FROM <1) TO -1. 
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THRU <2) Equivalent to FROM -1 THRU <2). 

TO <2) Equivalent to FROM -1 TO <2). 

<1) AND <2) AND ... Specifies a sequence of event 
specifications. 

ALL ¢1) Specifies all events satisfying 


the form given as (1). For 
example, ALL LOAD would consider 
all events having LOAD as the 
function. 


<empty)> No specification is the same as 
-1, i.e., the last event. 
However, if the last event was 
an UNDO, then it corresponds to 
a -2. 


@ <literal-atom) If <literal-atom) is the name of 
a command defined via NAME (see 
Section 28.4.8), this form 
specifies the event that defined 
<literal-atom), i.e., the event 
that saved the event which is 
the value of <literal-atom). 


@@ <1) An event specification that is 
interpreted with respect to the 
archived history list. 


Note that <1) and <2) may refer to the index of an event or the name of the 
function corresponding to the event. 

As an example, FROM TCOMPL could specify a sequence of events begin- 
ning with a recent compilation and progressing up to the most recent event. 

If the History Package cannot find any events that match the specification, 
it attempts spelling correction on the words in the specification using LISPX- 
FINDSPLST to correct possible misspellings. If the event specification still fails 
to identify any events, an error is generated. 


28.3.1 Event Addresses 


An event address, such as (1) above, is a specification of an event number in the 
history list. An event is located by moving an imaginary cursor up or down the 
history list. The event selected is the one that lies “under” the cursor when there 
are no more commands to be interpreted in the event specification. Each com- 
mand always moves the cursor. Addresses may be specified in the following 
ways: 


{n) 
“—n) 


“— <atom) 


SUCHTHAT <pred) 
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Move forward <n) events in the 
history list where n =) 1. 


Move backward -n events where n 
=) be 


Specifies an event whose 
function matches <atom). This 
form is used to select an event 
where (atom) was the function 
used in the event. 


Indicates the next search is to 
go forward rather than 
backwards; if given as the first 
address indicates that the 
search begins at the last 
element of the list. 


Indicates that the next object 
is a literal that is to be 
searched for, e.g., F -4 
searches for an event containing 
a -4 rather than moving 
backwards four events in the 
history list. 


Indicates that the next object 

in the address is to be matched 
against values of events rather 
than the inputs. 


Indicates the last event 
located. 


Specifies an event for which 
{pred), a predicate of two 
arguments, is true. The first 
argument is the input portion of 
the event. The second argument 
is the event itself. For 
example, 


SUCHTHAT 
(LAMBDA (X Y) 
(MEMBER '*ERROR* Y)) 


specifies an event in which an 
error occurred. 
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<atom) Specifies the name of a command 
defined by the NAME command (see 
Section 28.4.9). 


<pattern) Anything else which may be 
matched against the input of an 
event. 


28.4 HISTORY COMMANDS 


The History Package provides a powerful, flexible set of commands for modify- 
ing and re-executing expressions in the history list. All history commands take 
an event specification which is signified by <event). If (event) is omitted from a 
history command, then the value -1 is assumed (i.e., apply it to the previous 
event). 


28.4.1 Re-executing Previous Expressions 


You may re-execute a previous expression on the history list by executing the 
REDO command. The simplest form of this command is 


REDO <event) 
which executes the event(s) specified. 
REDO FROM -6 TO -3 


will do three events beginning six deep in the history list. Another form that is 
useful is 


REDO < atom) 


which looks for an entry in the history list whose function corresponds to (atom) 
and re-executes it. You may have performed a compilation, noted an error, fixed 
it via the Editor, and now wish to redo the compilation. You might give the 
command REDO COMPILE. 

You may re-execute an event a number of times using the form 


REDO <event)> <n) TIMES 


which re-executes the specified event (n) times where (n) =) 1. Given a list of 
M (M =) 5) elements, if the last event were 


(SETQ alist (CDR alist) ) 
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then 


REDO 5 TIMES 


would strip off the first five elements of the list. 
You may re-execute an event based on the value of some S-expression which 
is evaluated prior to interpreting the history command. The formats are 


REDO <event) WHILE <form) 
REDO <event) UNTIL « form) 


Suppose the last two events consisted of the following sequence: 


(SETQ myfilelist (CDR myfilelist)) 
(MAKEFILE (CAR myfilelist)) 


which runs through a list of files that I have maintained and creates a new ver- 
sion of each according to its File Package commands. I could execute these two 
expressions until MYFILELIST is exhausted by issuing the followng history 
command: 


REDO FROM -2 UNTIL (NULL MYFILELIST) 
which terminates when MYFILELIST is exhausted. 


The REPEAT Command 
Alternative forms of these two commands are 


REPEAT <event) 
REPEAT <event) WHILE/UNTIL <form) 


The former is equivalent to REDO <event) WHILE T and continues to exe- 
cute until an error occurs or the user interrupts execution via keyboard control. 

The general form of REDO (and its alternative REPEAT) allow you to per- 
form multiple executions of a previous event. A system variable REDOCNT is 
initialized to 0 when the command is interpreted. On each iteration, REDOCNT 
is incremented by 1. If the command terminates properly, the numer of itera- 
tions will be displayed. You may access REDOCNT in <form). 


28.4.2 Argument Substitution 


You may substitute a different expression in the input of an event and re-execute 
that event. Let the previous event be 
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(SETQ sin.of.point (SIN (DEGREES.TO.RADIANS point) )) 


You could also calculate the COS.OF.POINT by issuing the following his- 
tory command: 


USE COS.OF.POINT FOR SIN.OF.POINT AND COS FOR SIN IN -1 


which performs the appropriate substitutions and re-executes the expression. 
The general form of the USE command is 


USE <expression[1])> FOR <argument[1]} AND . 
<expression[n]) FOR <argument[n]) IN <event) 


The USE command requires three pieces of information: 


1. The expressions to be substituted, 
2. The arguments to be substituted for, 
3. An event specification. 


An expression may be preceded by a !. This indicates that it is to be substi- 
tuted as a segment, i.e., it replaces only a portion of the input statement. As- 
sume that ANGLES-IN-RADIANS is a variable. To substitute this variable into 
the expression, you could use 


USE ! ANGLES-IN-RADIANS FOR (DEGREES-TO-RADIANS POINT) 


You may omit the arguments in a USE command. There are two cases to be 
considered: 


1. The <event) is a USE command. The substitution takes place for the 
same arguments as the previous USE command. 
We could also compute the tangent of the point by issuing the com- 
mand 


USE ! TAN IN -1 


2. The event) is not a USE command. The substitution is performed for 
the operator in the specified event: 


a. If it was LISPX input, then the expression is substituted for the 
function in the input expression. 


USE CAR IN CDR 


b. If it was an edit command, then the expression is saa for 
the name of the command. 
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You may also omit the IN phrase in the USE command while specifying the 
arguments. In this case, the History Package uses the first item in arguments to 
build an event specification. It does so by implicitly inserting an F command 
with the first argument into an IN phrase in the USE command. 

So far, we have looked at USE commands that specify a one-for-one substi- 
tution between the expressions and the arguments. The History Package can 


distribute several expressions over the same argument. Various combinations 
are available. 


USE BALTIMORE MARYLAND FOR RICHMOND VIRGINIA 
is equivalent to saying 

USE BALTIMORE FOR RICHMOND AND MARYLAND FOR VIRGINIA 

We might also say 

USE BALTIMORE ELKTON HAGERSTOWN FOR CITY 
which substitutes BALTIMORE for CITY and executes the event, then substi- 
tutes ELKTON for CITY, and executes the event, and finally substitutes HA- 
GERSTOWN for CITY. 


An alternative form of the USE command, <ESC) (echoed as $), is used to 
specify character substitutions in strings and literal atoms. It basic forms are 


$ <x) FOR <y) IN event) or 
$ <y) <x) IN <event) 

$ <y) = <x) IN (event) 

$ <y) -) <x) IN event) 


which are equivalent to 

USE $<x)$ FOR $<y)$ IN <event) 
as used in 

$ COS FOR SIN IN -1 


would have the same effect as the previous history command given above. The 
event would be re-executed as 


(SETQ cos.of.point (cos (DEGREES.TO.RADIANS point) )) 
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$ may only be used to specify one substitution at a time. After it finds an 
event, $ determines if an error was involved in that event. If the indicated char- 
acter substitution can be performed in the offending object, the offender, $ per- 
forms the substitution in the offender only and then substitutes the result for the 
original offender throughout the remainder of the event. This is the most com- 
mon use of the $ command—to correct a spelling or other trivial character-based 
error in a command typed at the top level. Consider the following example: 


«(LOAD 'COOMPLEX) 
FILE NOT FOUND 
COOMPLEX 


<$ OO FOR O in LOAD 

00-0 

« KAISLER)COMPLEX. .6 

FILE CREATED 21-Nov-84 al rf he ty | 
COMPLEXCOMS 


$ never searches for an error. It performs the replacement in the offender 
only if the specified event caused an error. 


28.4.3 Editing a Previous Event 


Sometimes the previous expression is so complex that it becomes rather tedious 
to “‘write’’ the history commands to correct it. In these cases, it is easier to edit 
the expression and then re-execute it. You can edit a previous event by issuing 
the FIX command. It takes the form 


FIX <event) 


FIX puts you into the INTERLISP Editor with a copy of the input expres- 
sion which has been extracted from the event entry on the history list. When you 
exit the Editor with an OK, the result is substituted into the event and re-exe- 
cuted. Suppose we are defining a function: 


< (DEFINEQ 
(ADD3 (X Y Z) 
(IPLUS X YZ))) 
( ADD3) 


In my haste to enter the function definition, I concatenated the Y and Z. 
Instead of retyping the definition, I can fix it as follows: 


FIX 
edit 
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*P 

(DEFINEQ (ADD3 & & &)) 
*2 4 P 

(IPLUS X YZ) 

*(R YZ Y) 

*(N Z) 

*OK 

(ADD3 redefined) 
(ADD3) 


If the edition is relatively simple, you can specify a sequence of Editor com- 
mands following the FIX command which are applied to the expression. After 
the last Editor command, an implicit OK is assumed which forces the result to 
be re-executed. Thus, we could have performed the same editing as follows: 


+ (DEFINEQ 
(ADD3 (X Y Z) 
(IPLUS X YZ))) 
( ADD3) 


“FIX defineq-2 4 P (R YZ Y) 
seth 2) 


whence the Editor does not type edit or wait for an OK after executing the com- 
mands. 


28.4.4 Retrying an Event 


A particularly difficult problem to assess is the expression which enters an infi- 
nite loop or takes an unusually long time to execute. In these cases, you want to 
enter the Break Package after a given period of time to determine what has hap- 
pened. The RETRY command allows you to force breaks if a previous event 
executes in such a way as to cause errors that are not trapped. Its format is 


RETRY <event) 


If I wanted to reset my erroneous definition of ADD3 in order to demon- 
strate an alternative method of correcting it, I could retry the original event as 


follows: 


“RETRY 17 
(ADD3 redefined) 
(ADD3) 
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28.4.5 Printing the History List 


In manipulating the history list, you may forget what events have previously oc- 
curred (particularly if your terminal scrolls off the top as mine does—so does 
INTERLISP-D’s typescript window). You can inspect the history list by issuing 
the ?? command. ?? prints the history list. Unlike other commands, if the 
<event) is omitted, ?? will display the entire history list for you (beginning with 
the most recent event). 

Note that ?? commands are never entered onto history lists. Thus, they do 
not affect the relative event numbers. For example, ?? -1 refers to the event im- 
mediately preceding the ?? command. However, ?? does print the history com- 
mand associated with an event. You may distinguish the history commands by 
noting that they are not preceded by a prompt character. . 

?? is implemented by the function PRINTHISTORY which you may also 
invoke directly. Consider the following example: 


bast of 4 

37. RETRY 17 

(DEFINEQ (ADD3 (X Y Z) (* edited "24-Nov-84 09:17") 

(IPLUS X Y Z))) 

(ADD3 redefined) 

(ADD3) 

36. RETRY 2 

2? "because event 2 has fallen off the end of 
the history list" 

35. FIX DEFINEQ-2 4 P (R YZ Y) (N Z) 


34 

For each event, ?? prints the event number, the prompt character, the input 
line(s) and the value(s). If the event was a Programmer’s Assistant command 
that “unread” other input lines, the Programmer’s Assistant command will be 


printed without the prompt character to show that they are not stored as input, 
and the input lines will be printed with prompt characters. 


28.4.6 Undoing the Effects of Events 


You may undo the effects of a previous expression or command by executing the 
UNDO command. Its format is 


UNDO <event)> 


UNDO undoes the side effects of the specified events. For each event that is 
undone, the History Package prints a message of the form 


<function) UNDONE 
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where {function ) is in the input of the event. If nothing is undone because noth- 
ing was saved, the History Package merely types NOTHING SAVED. 


<-(DEFINEQ (GET.HEAD (LST) (CAR LST))) 
(GET.HEAD) 


*-UNDO DEFINEQ 
DEFINEQ undone 


«(PP GET.HEAD) 
(GET.HEAD not printable) 
(GET .HEAD) 


If nothing was undone because the event’s side effects were already undone, 
the History Package prints the message ALREADY UNDONE. When no event 
is specified, UNDO searches back through the history list until it finds an event 
that has side effects which were not undone and where the input is not another 
UNDO command. It undoes that event. 


You may undo the effects of UNDO commands. 


«-UNDO UNDO 
UNDO undone 


«(PP GET.HEAD) 
(GET .HEAD 
(LAMBDA (LST) **COMMENT** 
(CAR LST) )) 


In general, undoing events in the reverse order of execution will restore all 
INTERLISP pointers to their correct previous values. The easiest way to say this 
is UNDO THRU S. If you undo events in any other order, the state of the system 
is unpredictable because the expressions may have been dependent upon the 
sequence of execution. 

An alternative version of the UNDO command has the following form: 


UNDO <event) : <patterni) ... <patternN) 

Each (pattern[i]) is matched to a message printed by DWIM in the event 
specified by <event). The side effects of the corresponding DWIM corrections 
are undone. If DWIM had printed the following message: 

LOOAD [IN GET.FILES] -) LOAD 
performing the command 


UNDO : LOAD 


would undo the correction. 
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Note that some of the DWIM messages include strings. Merely typing an 
atomic form would not find the string. You must surround it by « ESC) charac- 
ters to locate it. 


28.4.7 Correcting Errors via DWIM 


When an error occurs, you can attempt to have DWIM fix it with information it 
already possesses such as spelling lists, etc. You do so by executing the history 
command DWIM which invokes DWIM to correct and re-execute the expres- 
sion. Suppose that you had typed the expression 


(GETPROP 'state 'capital) 


and had received NIL as the answer. Of course, the property name should be 
CAPITOL. If you had previously executed 


(PUTPROP 'state 'capitol) 


DWIM would have enough knowledge to correct the spelling of the property and 
retrieve the value, if any. 

Associated with certain commonly used functions are heuristics about how 
they are used. When a function fails, DWIM determines if one of these functions 
was involved in the input. If so, it uses the heuristic information to correct the 
erroneous condition. Usually, this heuristic information concerns spelling and 
the nature of the arguments. DWIM knows about the following functions: 


1. GETD, FNTYP, and MOVD all takes as their first argument an atom 
that should have a definition. 

2. GETP, GETPROP, GETPROPLIST, PUT, and PUTPROP take as a 
first argument an atom that should have a non-NIL property list and a 
second argument which should be a property on that property list or a 
member of SYSPROPS. 

3. SET, SETQ, and SETQQ take as a second argument a variable that is 

bound to some value which is assigned as the value of the first argument. 

LOADENS and EDITF take as an argument the name of a function that 

is contained on one of the files in FILELST (i.e., the function has already 

been loaded once). 


4 


If any of these conditions are not true for the expression, DWIM attempts to 
make them true through spelling correction. If the condition is made true, the 
corrected event is re-executed. 

If an error occurred in the indicated event due to a misspelling, DWIM can 
look for an atom that is ‘‘close to”’ the word that was originally intended. To do 
so, it appends $$ (i.e., two escapes <esc)) onto the end of the offender, substi- 
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tutes it into the event, and tries again. The History Package will then search for 


an event that has a word close to the offender and attempt to re-execute that 
event. 


(MOVE 3 2 TO AFTER CONDD 1) 


will cause the Editor to respond CONDD?. When you type DWIM, it substitutes 
CONDD esc) esc) into the event, which causes 


(MOVE 3 2 TO AFTER CONDD<esc) esc) 1) 


to be executed. It searches for an atom close to CONDD, which is COND, and 
this event is re-executed. 


If these procedures fail, DWIM displays the message 


Unable to figure out what you meant in: (event) 


28.4.8 Saving and Retrieving Events 


You may save and restore events on the property list of an atom. The form of 
these commands is 


NAME <literal-atom) (event) 
RETRIEVE <atom) 


The specified events, including the side effects, are stored on the property 
list of the atom under the property HISTORY. Events saved on the property list 
of the <literal-atom) may be retrieved using the event specification form: @<lit- 
eral-atom). 

This feature is quite useful when you are executing a sequence of expressions 
associated with an atom which you might want to repeat several times through- 
out the session. In particular, you may make beneficial use of it during the de- 
bugging of a program when you enter expressions to look at the values of various 
variables used by the program. 

In effect, you are describing a new command for the History Package by 
associating events with an atom. You may execute the command as a history 


command by merely typing its name. 


24 (DEFINEQ 
(CLEAR. ARRAY (XARRAY) 
(FOR I FROM 1 TO (ARRAYSIZE XARRAY) 


DO (SETA XARRAY I 0)))) 
(CLEAR. ARRAY) 


25+ (CLEAR. ARRAY XARRAY) 
NIL 
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26*-NAME CLEARA 25 
CLEARA 
27+*-CLEARA 
NIL 


which is equivalent to REDO 25. However, if <literal-atom) has a top-level 
value, then the value of the atom is returned (i.e., the atom is evaluated). Thus, 
you must be careful to define new history commands as atoms that do not have 
top-level values. 

Commands defined by NAME may be parametrized. The format of the 
NAME command is 


NAME <literal-atom) (<arguments)) : <event) 
or 

NAME <literal-atom) ... <arguments) ... : (event) 
where the <arguments) are interpreted as if a USE command had been given. 
Both !s and $s may also be used in specifying the structure of the arguments. 


Consider the following example: 


22+-(PUTD 'X (COPY (GETPROP 'Y 'EXPR))) 
(X) 


23*-NAME MOVE.DEFINITION X Y : PUTD 
MOVE.DEFINITION 


which defines the MOVE.DEFINITION command. Then, typing the statement 
24«-MOVE DUMP.MATRIX DUMP. ARRAY 
would result in the execution of the following expression: 
(PUTD 'DUMP.MATRIX (COPY (GETPROP 'DUMP.ARRAY 'EXPR) )) 
which is equivalent to executing 
USE DUMP.MATRIX DUMP.ARRAY FOR X Y IN MOVE.DEFINITION 
Commands, defined by NAME without arguments, which are invoked with 
arguments will cause errors. 
RETRIEVE extracts the events from the atom and re-enters them on the 


history list. It does not re-execute them. If <literal-atom) did not previously ap- 
pear in a NAME command, the History Package generates an error. 
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RETRIEVE <example) 


Once you have retrieved events from the HISTORY property of an atom, 


you may apply any history command to those events (including saving them on 
another atom). 


You may execute the events stored under the HISTORY property of an atom 
by executing a REDO command: 


REDO <literal-atom) 
is equivalent to 


RETRIEVE <literal-atom) 
REDO 


You may also see what events have been stored under the HISTORY prop- 
erty of an atom by executing 


2? <literal-atom) 


Suppose you have defined a new command via the NAME command. This 
command records events which have been applied to one or more variables. You 
may undo the effects of the events associated with the command by executing the 
history command BEFORE, which takes the form 


BEFORE <literal-atom) 


You may re-execute the events by executing the history command AFTER, 
which takes the form 


AFTER <literal-atom) 


BEFORE and AFTER allow you to “‘flip’”’ back and forth between two pro- 
gram states in order to test the effect of modifications to data structures or vari- 


able values. 
Both BEFORE and AFTER will generate an error if their argument was not 
previously defined via a NAME command. 


28.4.9 Archiving Events 


The History Package maintains a third history list which is a permanent history 
list. You may archive events on that history list by executing the ARCHIVE com- 


mand which takes the form 


ARCHIVE <event) 
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Events recorded on the archival history list may be referenced by preceding 
the event specification by @@. The @@ specification may be used with any 
history command subject to other restrictions as previously noted. 

Events may automatically be archived when they are about to be forgotten 
by defining ARCHIVEFN (see Section 28.5.3) to do the proper thing. 


28.4.10 Forgetting Side Effects 


As we noted previously, events may (and often do) have side effects. You may 
forget the side effects associated with an event by executing the history command 
FORGET, which takes the form 


FORGET <event) 


If <event) is omitted, the side effects for the entire history list are forgotten. 
Note that FORGETing is not undoable. 

Many INTERLISP functions preserve old pointers in the side effects of an 
event when new values are created. Among these functions are SETx, PUTD, 
REMPROPS, COPY, etc. The old pointers are not garbage collected until the 
event is forgotten from the history list. You may force garbage collection (at the 
next appropriate time) of these pointers by FORGETting them from the side 
effects of their respective events. 

The IRM notes that this function is provided for users with space problems. 
You probably do not need to worry about this situation if you are running under 
INTERLISP-D unless you have reset the maximum number of events to a fairly 
large number and are running a problem that has very large and complex data 
structures. 


28.4.11 Remembering Events 


You may remember events across sessions by saving the events in a file. The 
REMEMBER command causes the File Package to remember events as in- 
stances of the File Package type EXPRESSIONS? whenever a FILES?, MAKE- 
FILES, or CLEANUP (see Section 17.3.6) is executed. The File Package writes a 
command of the form (P <event)) into the COMS of the specified file. 


28.4.12 Printing Property Lists 


You may print the property list of an atom by executing the history command 
PL, which takes the form 


PL <atom) 


PL prints the property list of the specified atom with the print level (see 
Section 15.3) temporarily reset to (2 . 3). 
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“-PL MASTERSCOPE 
FILEDATES : ((" 4-Aug-83 23:47:11" . 
«NEWLISP )MASTERSCOPE. ;1)) 


PL is equivalent to executing GETPROPLIST upon the name of the atom. 


28.4.13 Printing Atom Bindings 


You may print the binding (i.e., the value) of an atom by executing the history 
command PB, which takes the form 


PB <atom) 


Its primary purpose is to allow you to inspect the values of atoms which may 
have complex data structures. 


“PB LISPXHISTORY 
@ TOP : ((& & --) 17 30 ==) 


Note that the effect of PB is mediated by the current setting of the print 
level. 


«PB X 
@ TOP : NOBIND 


Note that if the atom is not bound, the History Package will not attempt 
spelling correction or generate an error. 


28.4.14 Analyzing Errors 


When a: error occurs in an expression, you can ask the Programmer’s Assistant 
to attempt an analysis of the error. You do so by executing the history command: 


2 


The Programmer's Assistant attempts to analyze the nature and cause of the 
error using context information saved when the input of the event was executed. 
Based on this analysis, it will try to put you into the Editor at the proper location 
to correct the problem. Consider the following example: 


<—(DEFINEQ (GET.HEAD (LST) (CARR LST))) 
(GET.HEAD) 


<(GET.HEAD '(MUSIAL MANTLE MARIS) ) 


UNDEFINED CAR OF FORM 
CARR [in GET.HEAD] in [CARR LST] 
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=? 

edit 

(LAMBDA (LST) **COMMENT** (CARR LST) ) 
1% 


28.4.15 Bypassing the Programmer’s Assistant 


Every line that you type into LISPX will be examined and processed by the Pro- 
grammer’s Assistant. You may force this processing to be bypassed by entering a 
command of the form 


: €expression) 


The : allows you to enter input to the system without having it processed by 
the Programmer’s Assistant. 


28.4.16 Preventing History List Recording 


Every expression submitted to the top-level READ-EVAL-PRINT loop is re- 
corded on the history list unless it is one of the excepted Programmer’s Assistant 
commands. Note that the amount of information saved for each event varies with 
the nature of the expression that you type in (see the example above). You may 
prevent the recording of an expression on the history list using the SHH com- 
mand, which takes the form 


SHH <statement) 


where (statement) may be either an S-expression or a Programmer’s Assistant 
command, 


28.5 HISTORY PACKAGE VARIABLES 


The History Package uses a number of variables to determine how it will respond 
to certain commands and how it will treat certain events. These variables are 
described in this section. 


28.5.1 LISPX History Macros 


LISPXHISTORYMACROS is a variable whose value is a list of elements of the 
form 


(<command) <definition) ) 


LISPXHISTORYMACROS allows you to define your own History Package 
commands. When (command) is recognized on type-in, (definition) is evalu- 
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ated. However, unlike LISPXMACROS, its result is treated as a set of expres- 
sions which are to be unread. That is, the result of evaluating (definition) is 
placed at the front of READBUFFER (see LISPKUNREAD). It is permissible 


to return NIL as the result of evaluating < definition) which means nothing else is 
to be done. 


LISPXHISTORYMACROS takes as its initial value (comments added for 


understanding in this listing) 


((QU 
(* 
Quit from INTERLISP 
) 
NIL 
(LOGOUT) 
(BUF 
(* 
Put input into the read buffer. TTYIN is an 
INTERLISP-D function. 
) 
NIL 
(TTYIN LISPXID 
NIL 
NIL 
"EVALQT 
NIL 
NIL 
(LIST 
(COND 
(LISPXLINE 
(VALUEOF LISPXLINE) ) 
(T 
(CADDR (CAAR LISPXHISTORY) )))))) 
(DA 
(PROGN 
(* 
Print the date and time on the terminal; 
and move to the next line. 
) 
(LISXPRIN1 (DATE) T) 
(TERPRI T))) 
(; NIL NIL) 
(PB 
(* 


A macro definition for the PB command. 


) 
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(MAPC LISPXLINE 


(FUNCTION 
(LAMBDA (X) 
(PRINTBINDINGS X 
(AND 
(EQ LISPXID ':) 
ti LASTPOS) ) )))) 
(* 
A macro definition for the PL command. 
(COND 
(LISPXLINE 
( (PRINTPROPS (CAR LISPXLINE) ) ) 
T 
'(E PL)))) 
(2? 
NIL 
(PROG (TEMP) 
(RESETVARS 
((PRETTYTRANFLG T) ) 
(RESETFORM 
(OUTPUT T) 
(PRINTDEF 
(COND 
( (NULL 
(CDAR 
(SETQ TEMP 
(LISPXFIND 
LISPXHISTORY 
LISPXLINE 
'ENTRY) ) ) ) 
(CAAR TEMP) ) 
(T 
(CAR TEMP) )) 
NIL 
T))) 
(TERPRI T) 
(RETURN NIL) )) 
(TYPE-AHEAD 
(LISPXTYPEAHEAD) ) ) 


28.5.2 History Package Forms 


Several variables have as their values a list of expressions to be evaluated when 
certain functions are executed: 
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PROMPTCHARFORMS A list of expressions to be 
executed each time PROMPTCHAR 
(see Section 25.6) is called. 


HISTORYSAVEFORMS A list of expressions to be 


executed each time HISTORYSAVE 
(see Section 28.6.1) is called. 


Note that expressions on PROMPTCHARFORMS will be evaluated before 
the prompt character is printed. The expressions on HISTORYSAVEFORMS 
are executed after the user has completed type-in, but before the input is evalu- 


ated. Thus, you may effectively encapsulate the user’s interaction with the sys- 
tem (or subsystem). 


RESETFORMS A list of expressions to be 
evaluated whenever (RESET) is 
executed, when the user types 
CTRL-D, or when the user types 
CTRL-C followed by START. See 
Section 25.7 for more 
information. 


28.5.3 The Archival Function 


ARCHIVEEN is a History Package variable whose value determines whether or 
not an event about to be forgotten will be archived or not. The value of AR- 
CHIVEFN is initially NIL and undefined so that all events passing the age 
threshold will be forgotten. You may set ARCHIVEFN to T whence the defini- 
tion stored in the function definition cell of ARCHIVEFN will be called to deter- 
mine how to process the event. 

The definition stored in the function cell of ARCHIVEFN must be a 
LAMBDA expression of two arguments: the input portion of the event and the 
entire event. If the function returns T, the event is archived on ARCHIVELST. 
ARCHIVELST is initially NIL. 

To record all events concerning the loading of files, you would set AR- 
CHIVEEN to T and define it as follows: 


(LAMBDA (INPUT EVENT) 
(EQUAL (CAR INPUT) 'LOAD)) 


ARCHIVEEFLG is a flag that determines how events referenced by history 
commands are to be processed. The rationale is that if you reference a previous 
event by a history command, it must be important (i.e., may be referenced 
again). Thus, when it falls off the end of the history list, it should be archived. If 
ARCHIVEFLG is non-NIL, the History Package automatically marks every 
event referenced by a history command so that it will be archived. AR- 
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CHIVEFLG is initially T. Events are marked for archiving by placing the prop- 
erty *ARCHIVE* with value T in the event entry. 

ARCHIVELST is initialized to (NIL 0 50 100) so that it does not have an 
indefinite length. 


28.5.4 The Value of an Event 


The History Package variable IT always stores the value of the most recent event. 
It may be used in succeeding expressions or history commands just like any other 
variable. Consider the following example: 


<(SQRT (TIMES 100 50)) 
70 .71068 


aga 
70.'71068 


<(SQRT IT) 
8.408964 


28.6 HISTORY PACKAGE FUNCTIONS 


The History Package provides a number of functions that allow you program- 
matic access to the history lists from within your program or that allow you to 
maintain you own history lists that are application dependent. The latter feature 
is very useful in many artificial intelligence programs that require a history of 
decisions in order to implement an explanation facility. This section will discuss 
the History Package functions. 


28.6.1 Recording a History Event 
HISTORYSAVE records an event on a history list. It takes the form 


Function: — HISTORYSAVE 
# Arguments: 6 . 
Arguments: 1) a history list, HISTORY 


2) an event identifier, ID 

3) an input specification, INPUT1 
4) an input specification, INPUT2 
5) an input specification, INPUT3 
6) a list of properties, PROPS 


Value: The new event identifier. 


HISTORYSAVE creates a new event with an event identifier having the 
value of ID. The value field of the event is initialized to bell (?). The event has the 
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associated properties and values that are the value of PROPS. If the size of HIS- 


TORY has reached its maximum, the last event (e.g., the oldest) is removed 
from the list. 


INPUT1, INPUT2, and INPUT3 describe the possible forms of the input 
sequence that produced the event: 


1. If INPUT1 is non-NIL, the input entry is of the form 
(INPUT1 INPUT2 . INPUT3) 

2. If INPUT1 is NIL and INPUT2 is non-NIL, the input entry is of the form 
(INPUT2 . INPUT3) 

3. Otherwise, the input entry is just INPUTS. 


The value of HISTORYSAVE is the new event. 

If REREADFLG in non-NIL, and the most recent event records a command 
that produced this input, HISTORYSAVE does not create a new event but 
merely updates that event’s *GROUP* property with an entry of the form (<in- 
put) <id) <bell> . <props)). 


“SHH (HISTORYSAVE LISPXHISTORY 54 'HISTORYSAVE) 
((HISTORYSAVE NIL) 54) 


which is the structure of the new event. Note that you may evaluate a value and 
place it in the event using RPLACD. 

HISTORYSAVE uses HISTORYSAVEFORMS when it creates a new 
event. If HISTORYSAVEFORMS is non-NIL, it should be a list of expressions 
that is evaluated (under ERRORSET protection) each time a new event is cre- 
ated. These expressions may use the values of the arguments to HISTORYSAVE 
as well as the variable EVENT which is the value that HISTORYSAVE is about 
to return. 


28.6.2 Locating a History Event 


HISTORYFIND searches the history list to find a specified event. It returns the 
tail of the history list beginning with the event that was looked for. It takes the 


form 
Function: HISTORYFIND 


# Arguments: 4 


Arguments: 1) a history list, HISTORY 
2) an index into the history list, INDEX. 
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3) the maximum event #, MOD 
4) an event specification, EVENTADR 


Value: The tail of the history list beginning 
with the specified event; otherwise, an 
error. 


Consider the following example: 


2+ (SETQ COMPOSERS 
(LIST 'BACH 'BEETHOVEN 'COPELAND 'MOZART) ) 
(BACH BEETHOVEN COPELAND MOZART) 


3«-PB COMPOSERS 
@ TOP : (BACH BEETHOVEN COPELAND MOZART) 


4<-(HISTORYFIND (CAR LISPXHISTORY) 2 4) 

((NIL _ *HISTORY* ((PB COMPOSERS)) *GROUP* NIL) (((SETQ 
COMPOSERS (LIST (QUOTE BACH) (QUOTE BEETHOVEN) (QUOTE 
COPELAND) (QUOTE MOZART)))) _ (BACH BEETHOVEN COPELAND 
MOZART) SIDE (4 (UNDOSET NIL COMPOSERS NOBIND) (ADDSPELL2 
COMPOSERS ("'spellseparator" ... (rest of spelling list) 


Note that the first argument to HISTORYFIND uses the CAR of the actual 
history list because it should be the history list itself. 


28.6.3 Locating Events by Specification 


LISPXFIND searches a history list and returns a structure consisting of the 
events that match a given specification. It takes the form 


Function: LISPXFIND 
# Arguments: 4 


Arguments: 1) a history list, HISTORY 
2) an event specification, EV 
3) a format specification, TYPE 
4) a backup flag, BACKUP 


Value: As described below. 


LISPXFIND attempts to locate the corresponding history events to the spec- 
ification given by EV. EV is an event specification. TYPE specifies the format of 
the value to be returned by LISPXFIND. It is chosen from ENTRY, ENTRIES, 
COPY, COPIES, INPUT, or REDO. LISPXFIND parses EV and call HIS- 
TORYFIND to locate and assemble the specified events. 
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2+ (SETQ COMPOSERS 
(LIST 'BACH 'BEETHOVEN 'COPELAND 'MOZART)) 
(BACH BEETHOVEN COPELAND MOZART) 
3«-PB COMPOSERS 
@ TOP : (BACH BEETHOVEN COPELAND MOZART) 
«-(LISPXFIND LISPXHISTORY '(SETQ) 'ENTRY T) 
(((SETQ COMPOSERS (LIST (QUOTE BACH) (QUOTE BEETHOVEN) 
(QUOTE COPELAND) (QUOTE MOZART)))) _ (BACH BEETHOVEN 


COPELAND MOZART) SIDE (4 UNDOSET NIL COMPOSERS NOBIND) 
(ADDSPELL2 ...))) 


BACKUP is a flag that is interpreted as follows: 


1. If BACKUP is T, LISPXFIND looks for an event in the history list prior 
to the insertion of the current event so that it will not refer to itself. 


2. If EV is NIL and the last event was the Programmer’s Assistant com- 
mand UNDO, the next to last event is retrieved from the history list. This 
permits you to type UNDO followed by REDO or USE. 


3. ARCHIVELST will be substituted in place of the specified history list if 
EV contains @@ within its value. 


4. If EV contains @, LISPXFIND will retrieve the event from the corre- 
sponding literal atom rather than the specified history list. 


I recommend that you always use LISPXFIND with BACKUP set to T. 


28.6.4 Extracting a History Event 
ENTRY# extracts an event from a history list. It takes the form 


Function: ENTRY# 
# Arguments: 2 


Argument: 1) a history list, HISTORY 
2) an event specification, EVENT 


Value: The event number for EVENT. 


«(ENTRY# LISPXHISTORY '(SETQ)) 
100 


28.6.5 Obtaining an Event’s Value 


VALUEOF obtains the value of an event on the current history list. It takes the 
form 
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Function: VALUEOF 

# Arguments: 1 

Argument: 1) an event specification, EVENT 
Value: The value of the corresponding event. 


VALUEOF is an NLAMBDA, nospread function. Consider the following 
example: 


<(VALUEOF 11) 
(BACH BEETHOVEN COPELAND MOZART) 


Note that if VALUEOF cannot find a value for the specified event, it returns 
the maximum event number. 


28.6.6 Changing a History List’s Timeslice 


CHANGESLICE allows you to change the timeslice for a history list. As you 
remember, the timeslice is the number of events that will be recorded on the 
history list. It takes the form 


Function: CHANGESLICE 
# Arguments: 2 
Arguments: 1) a timeslice, N 
2) a history list, HISTORY 
Value: The value of timeslice. 


The effect of increasing the time slice is a gradual lengthening of the history 
list as new events are recorded. Decreasing the time slice will cause the excising 
of enough events to reduce the history list to the proper size. Because 
CHANGESLICE is undoable, these events are recoverable. Consider the follow- 
ing example: 


«PB LISPXHISTORY 

@ TOP : ((& & --) 19 30 --) 
<(CHANGESLICE 1 LISPXHISTORY) 
1 is too small 

<(CHANGESLICE 3 LISPXHISTORY) 
‘ 


<-PB LISPXHISTORY 
@ TOP : ((& & --) 23 3 --) 
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28.6.7 Searching the History List 


HISTORYMATCH is used to match patterns against input portions of events on 


a history list in order to identify an event. It is primarily used by HISTORY- 
FIND. It takes the form 


Function: HISTORYMATCH 
# Arguments: 3 
Arguments: 1) an input entry, INPUT 


2) a pattern, PATTERN 
3) an event specification, EVENT 


Value: As returned by EDITFINDP. 


HISTORYMATCH is used by HISTORYFIND to match the pattern given 
by PATTERN against an entry from the specified history list. HISTORYFIND 
maps over the entries on the history list while calling HISTORYMATCH. It is 
initially defined as (EDITFINDP INPUT PATTERN T). 


28.6.8 Printing the History List 
PRINTHISTORY allows you to print a history list on a file. It takes the form 


Function: PRINTHISTORY 
# Arguments: 5 


Arguments: 1) a history list, HISTORY 
2) an event specification, EVENT 
3) a skip function, SKIPFN 
4) a values flag, NOVALUES 
5) a file name, FILE 


Value: A display of the events on the file. 


PRINTHISTORY is used by the Programmer’s Assistant command ?? to 
display the history list. You may display portions of the history list from within 
your program using it. Alternatively, it is useful if you keep your own history list 
for user interaction with a program since these events are not typed in at the top 
level and so are not recorded on LISPXHISTORY. 

SKIPENS is a functional argument (i.e., a LAMBDA expression) that is 
applied to each entry on the history list. If it returns a non-NIL value, that entry 
will not be printed. 

If NOVALUES has the value T, the value will not be printed. This is usually 
the case when you want to display entries from EDITHISTORY. 


29 





Miscellaneous Functions and 
Features 


INTERLISP provides a number of functions that seem to be orphans, i.e., they 
do not fit into any of the categories that we have already identified. This section 
describes these functions. In many cases, these functions are implementation 
dependent; they may not be supported in all INTERLISP systems. 

In this text, I have omitted discussion of some of the functions that are im- 
plementation dependent. You should consult the INTERLISP Reference Man- 
ual for the proper calling sequences and parameters associated with these capa- 
bilities. 


29.1 CHRONOMETRIC AND COUNTING FUNCTIONS 


INTERLISP provides several functions for obtaining the current time and/or 
date. It also provides two functions for measuring the amount of time IN- 
TERLISP spends in performing certain types of computations. 


29.1.1 Date and Time Functions 


You may obtain the current date and time, formatted as a single string, by exe- 
cuting DATE, which takes the following form 


Function: DATE 

# Arguments: 0 

Arguments: N/A 

Value: A string representing date and time. 


DATE returns a string having the format 
"dd-mm-yy hh:mm:ss" 
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where dd is the day 
mm is the month 
yy is the year 
hh is the hour 
mm is the minute 
ss is the second. 


The current date would appear as 


+ (DATE) 
"28-OCT-83 07:17:34" 


The date is obtained from the host operating system under which IN- 
TERLISP is implemented. The granularity of the time value is dependent on the 
accuracy of the clock maintained by the host operating system. 


Obtaining the Date as a Large Integer 
Another chronometric function is IDATE, which takes the form 


Function: IDATE 

# Arguments: 1 

Argument: 1) a date and time string, DT 
Value: An integer representation of DT. 


IDATE converts DT to an integer representation. Given two data and time 
strings, DT1 and DT2, if DT1 is earlier than DT2, then IDATE[DT1] ¢ IDA- 
TE[DT2]. If DT is NIL, IDATE returns the value associated with (DATE). 


<— (IDATE) 

466167809 

+ (DATE) 

"28-OCT-83 07:17:34" 


A single integer value representing the date is useful for time-stamping en- 
tries in a list because it takes less space than a string. 


Obtaining the Date and Time as a String 
GDATE converts an internal date-and-time format into a date-time string. It 


takes the form 


Function: GDATE 
# Arguments: 3 
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Arguments: 1) an internal date-and-time, DT 
2) a format, FORMATBITS 
3) a string pointer, STRPTR 


Value: A formatted date-time string. 


The value of DT is equivalent to that produced by IDATE. If DT is NIL, 
then the value of (IDATE) is used. 


+ (GDATE) 
"28-OCT-83 07:18:53" 


+(GDATE (IDATE)) 
"27-Nov-84 13:02:28" 


+(SETQ DT (IDATE)) 
12066947650 


<(GDATE DT) 
"27-Nov-84 13:03:11" 


FORMATBITS is used by INTERLISP-10 to format the string using the 
TENEX/TOPS20 operating system routines. 

Note that you may use IDATE to time-stamp a list element, but later recover 
the corresponding string using GDATE. 


29.1.2 Clock Functions 


Most INTERLISP systems can reference the time-of-day clock that is main- 
tained by the system hardware. CLOCK returns various measures of time based 
on values extracted from the time-of-day clock. It takes the form 


Function: CLOCK 

# Arguments: 1 

Argument: 1) a format indicator, N 
Value: As described below. 


The value of N indicates which of four possible measures will be returned by 


CLOCK: 


0 
The current value of the time-of-day clock in milliseconds. This value is 


equivalent to the number of milliseconds that have elapsed since the system was 
started up. 


< (CLOCK) 
-1983526334 
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1 
The number of milliseconds since this session of INTERLISP was started. 


“(CLOCK 1) 
-1990867982 


2 
The number of milliseconds of compute time since this INTERLISP was 
started (garbage collect time is subtracted off). 


(CLOCK 2) 
2311790 


3 
The number of milliseconds of compute time spent in garbage collection. 


«(CLOCK 3) 
268915 


_ The values returned by CLOCK are not valid inputs to GDATE. 


«(GDATE (CLOCK)) 
''9-May-1861 06:49:39" 


29.2 SYSTEM FUNCTIONS 


Because INTERLISP is usually implemented as an applications program run- 
ning under control of an operating system, it provides a number of system func- 
tions that allow you to interact with the external environment. Functions de- 
scribed in this section are very dependent upon the nature of the underlying 
operating system. The values used in the examples are drawn from INTERLISP 
running on a Xerox 1100 Scientific Information Processor or INTERLISP-10 
running on a DECSystem-20. 


29.2.1 Exiting INTERLISP 
To exit INTERLISP, you use the function LOGOUT, which takes the form 


Function: LOGOUT 
# Arguments: 1 
Argument: 1) a fast exit indicator, LOGOUTFLG 


Value: Meaningless. 
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LOGOUT exits INTERLISP and returns control to the underlying operat- 
ing system. If LOGOUTFELG is T, INTERLISP exits without updating the vir- 
tual memory file that is maintained on the external disk. Thus, you probably will 
not be able to restart INTERLISP without first initializing it. (This fact is guar- 
anteed under INTERLISP-D!). If LOGOUTFLG is NIL (as is usually the case), 
INTERLISP updates the virtual memory file by writing “dirty pages’ from 
memory to the disk before returning control to the operating system. 

LOGOUT has no value since it never returns to the user. However, if you 
restart INTERLISP using the virtual memory stored on disk, it will resume oper- 
ation after the LOGOUT function invocation which will have the value NIL. 
Your program may continue from this point as if nothing had happened, save for 
the difference in time. 


29.2.2 Obtaining the System Type 


Because implementations of INTERLISP differ for various systems, it may be 
necessary for your program to know which system it is running on. SYSTEM- 
TYPE returns an atom which indicates the current system on which you are run- 
ning. It takes the form 


Function: SYSTEMTYPE 
# Arguments: 0 


Arguments: N/A 
Value: A literal atom corresponding to the system 
type. 


Consider the following examples: 


< (SYSTEMTYPE) 

D "indicating a Xerox 1100 (a.k.a. 
Dolphin)" 

< (SYSTEMTYPE) 

TOPS20 "indicating a DECSystem-20 computer" 


You may use the value returned by SYSTEMTYPE to determine what code 
to execute or compile. This is most easily coded using the form 


(SELECTQ (SYSTEMTYPE) 
(TOPS20 .. =) 
(D 

etc. 


1036 Miscellaneous Functions and Features 


29.2.3 Obtaining the User Name 


You may configure your program or your INTERLISP environment to operate 


differently depending on the user who is logged into it. USERNAME takes the 
form 


Function: USERNAME 

# Arguments: 2 

Argument: 1) a directory flag, DFLAG 
2) a type flag, TFLAG 

Value: As described below. 


If DFLAG is NIL, USERNAME returns the name of the login directory 
owner. For Xerox 11xx systems, this name is written into the disk partition direc- 
tory when the disk is initialized. 


+ (USERNAME) 
"GOLDEN TIGER" 


If DFLAG is T, USERNAME returns the name of the currently connected 
directory. 


«(USERNAME 'T) 
[100#]<KAISLER) LISP 


TFLAG determines what type the value is returned as. If TFLAG is NIL, the 
value is returned as a string. If it is T, the value is returned as a literal atom. 


«(USERNAME NIL T) 
KAISLER 


TFLAG may also be a string pointer whence the new string value is smashed 
into the location referenced by the pointer. 


29.3 PERFORMANCE MEASURING FUNCTIONS 


INTERLISP provides several functions for measuring the performance of your 
program in order to tune it. These functions are implementation-dependent. 
Their usage is described here for INTERLISP-10, but they will be discussed for 
INTERLISP-D in volume 2. 


29.3.1 Counting CONS Operations 


CONSCOUNT returns the number of CONSes since INTERLISP started up. 
Since all of the basic operations in INTERLISP ultimately become CONS opera- 
tions, it may be used as a measure of system efficiency. It takes the form 


29.3 Performance Measuring Functions 1037 


Function: CONSCOUNT 

# Arguments: 1 

Argument: 1) a new value, N 
Value: The current CONS count. 


If N is non-NIL, CONSCOUNT sets the CONS counter to N after returning 
its current value. Typically, N is 0, so that you may measure the number of oper- 
ations that a single expression or a function execution requires. 


<-(CONSCOUNT 0) 
611962 


 (CONSCOUNT) 
15 


29.3.2 Counting Page Faults 


PAGEFAULTS determines the number of page faults that have occurred in your 
INTERLISP system. Originally, it was intended for use with earlier versions of 
INTERLISP where physical memories were a few hundred thousand bytes or so. 
However, even with the current size of memories, it is still a useful function for 
determining something about the efficiency of your implementation and pro- 
gram construction. It takes the form 


Function: PAGEFAULTS 

# Arguments: 0 

Arguments: N/A 

Value: An integer representing the number of page 
faults. 


PAGEFAULTS returns a number that is the number of page faults that 
have occurred since INTERLISP was started up. 


< (PAGEFAULTS) 
8717 


Using PAGEFAULTS requires some knowledge about how your program is 
constructed. When you load a file, new atoms are allocated for the names of 
objects in the file, and memory is allocated for their values and function defini- 
tions. This allocation occurs in virtual memory. If you load a large number of 
files, virtual memory allocations will exceed physical memory. Excessive page 
faults require additional disk reads and writes, thus reducing the efficiency of 


your application. 
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29.3.3 Timing an Expression 


You may compute the execution time of an expression using the function TIME, 
which takes the form 


Function: TIME 
# Arguments: 3 


Arguments: 1) an expression to be timed, TIMEX 
2) a repetition factor, TIMEN 
3) the type of timing, TIMETYPE 


Value: The value of the last execution of TIMEX. 


TIME is an NLAMBDA function. It evaluates the expression TIMEX and 
prints out the number of CONSes and the computation time. Garbage collection 
time is subtracted out. Consider the following example (under INTERLISP-10): 


+-(SETQ PRESIDENTS '(FORD NIXON REAGAN HOOVER MCKINLEY) ) 
(FORD NIXON REAGAN HOOVER MCKINLEY) 


<-(TIME (CAR PRESIDENTS) ) 
O conses 

-001 seconds 

FORD 


<(TIME (LAST PRESIDENTS) ) 
0 conses 

.006 seconds 

(MCKINLEY) 


<(TIME (APPEND PRESIDENTS (LIST 'CARTER)) ) 
6 conses 

-005 seconds 

(FORD NIXON REAGAN HOOVER MCKINLEY CARTER) 


If TIMEN is greater than 1, TIMEX will be executed TIMEN times. 
TIMEN equal to NIL is assumed to be mean 1. The resulting number of conses 
and computation times are divied by TIMEN to produce an average over multi- 
ple cases. Consider the following example: 


<(TIME (COPY PRESIDENTS) 20) 
100/20 = 5 conses 

.016/20 = .0008 seconds 

(FORD NIXON REAGAN HOOVER MCKINLEY) 


TIMETYPE controls the printing of additional information regarding the 
execution of TIMEX. If TIMETYPE has the value 0, TIME will measure and 
print the total real time as well as the computation time. 
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<— (TIME (LOAD "COMPLEX) NIL 0) 
«KAISLER) COMPLEX. .6 

FILE CREATED 21-Nov-84 20:27:17 
COMPLEXCOMS 

1524 conses 

2.041 seconds 

6.845 seconds, real time 


If TIMETYPE has the value 3, TIME will measure and print the garbage 
collection time as well as the computation time. 


«-(TIME (LOAD 'COMPLEX) NIL 3) 
«KAISLER) COMPLEX. .6 

FILE CREATED 21-Nov-84 20:27:17 
COMPLEXCOMS 

1509 conses 

1.922 seconds 

.526 seconds, garbage collection time 


If TIMETYPE has the value T, TIME will measure and print the number of 
page faults. 


29.3.4 Breaking Down Performance by Function 


You may break down the statistics collected by TIME on a function by function 
basis using BREAKDOWN, which takes the form 


Function: BREAKDOWN 

# Arguments: 1-N 

Arguments: 1-N) function names, FN[1] ... FN[n] 
Value: A list of functions that have been timed. 


BREAKDOWN is an NLAMBDA, nospread fucntion. Its arguments are a 
list of function names which are modified to accumulate various statistics. When 
you have finished monitoring the performance of these functions, you may re- 
move them from the monitoring process via UNBREAK. Each time you call 
BREAKDOWN, new functions may be added to the list of functions that are 
being monitored and the counters for all functions currently on the list are set to 
zero. BREAKDOWN takes care not to “‘doublecharge’’ time to two functions. 
This may occur when two functions are to be measured and one calls the other. 


Displaying the Results of BREAKDOWN 
The results accumulated by BREAKDOWN may be analyzed and displayed by 


BRKDWNRESULTS, which takes the form 
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Function: BRKDWNRESULTS 

# Arguments: 1 

Arguments: 1) a return values flag, RETVALFLAG 
Value: Depends on the value of RETVALFLAG. 


BRKDWNRESULTS will print an analysis of the statistics and number of 
calls to each function noted on the monitoring list. If RETVALFLAG is nan- 
NIL, BRKWDNRESULTS does not print the analysis, but returns the values in 
a list whose entries are 


(<function) <#calls) <value)) 


Consider the following example: 


«(BREAKDOWN CMULT TIMES REAL IMAG PLUS DIFFERENCE 
COMPLEX) 
(CMULT TIMES REAL IMAG PLUS DIFFERENCE COMPLEX) 


<(SETQ CX1 (COMPLEX 1.0 3.0)) 


((1.0 . 3.0)) 
<(SETQ CX2 (COMPLEX 4.0 10.0)) 
((4.0 . 10.0)) 


<—(SETQ CX3 (CMULT CX1 CX2)) 
((-26.0 . 22.0)) 


< (BRKDWNRESULTS) 

FUNCTION TIME # CALLS PER CALL % 

CMULT O11 1 .011 2 

TIMES .022 4 .006 3 

REAL .097 7 .014 14 

IMAG .038 7 .005 5 

PLUS .006 2 .003 1 | 
DIFFERENCE .004 1 .004 1 | 
COMPLEX .085 3 .028 12 

SETQ .430 4 .107 62 

TOTAL .693 29 .024 

NIL 


<-(BRKDWNRESULTS T) 
((CMULT 1 11) (TIMES 4 22) (REAL 7 97) (IMAG 7 38) (PLUS 
2 6) (DIFFERENCE 1 4) (COMPLEX 3 85) (SETQ 4 430)) 


BREAKDOWN may also be used to gather other statistics by setting the 
value of the variable BRKDWNTYPE prior to calling BREAKDOWN. The 
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Sate of statistics that may be gathered are given by the value of BRKDWN- . 
ES: 


+-(PRINTDEF BRKDWNTYPES) 
((TIME (CPUTIME) 
(LAMBDA (X) 
(FQUOTIENT X 1000))) 
(CONSES (CONSCOUNT) ) 
(PAGEFAULTS (PAGEFAULTS) ) 
(BOXES (IBOXCOUNT) ) 
(FBOXES (FBOXCOUNT) ) 


Each entry should have the form 
(<type) <expression) <function)) 


where <type) is a statistic name 
: 2xpression) is an S-expression that computes the 
statistic 


<function) may convert the statistic value to 
some more interesting quantity or 
format 


By setting BRKDWNTYPE to one or more of the quantities listed above, 
BREAKDOWN makes the necessary changes to gather the statistics. The func- 
tions to be monitored will be redefined to gather the appropriate statistic. 

Some of the functions that you are analyzing may be fast enough that the 
overhead involved in measuring the functions obscures the actual time spent in 
the function. In a manner similar to TIME, you may specify a value in BREAK- 
DOWN that specifies that a function will be executed more than once. 


«(BREAKDOWN 10 CMULT TIMES REAL IMAG DIFFERENCE PLUS 


COMPLEX) 
(CMULT TIMES REAL IMAG DIFFERENCE PLUS COMPLEX) 


<(SETQ CX3 (CMULT CX1 CX2)) 
((-26.0 . 22.0)) 


< (BRKDWNRESULTS) 

FUNCTIONS TIME # CALLS PER CALL % 
CMULT .189 sf .189 24 
TIMES 796 40 .020 103 
REAL 1.718 41 042 223 
IMAG 1.749 41 £043 227 
DIFFERENCE .150 10 .015 19 
PLUS 2.103 110 .019 272 
COMPLEX 1.013 10 .101 131 
TOTAL 772 253 .003 


NIL 
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_ 29.4 SESSION TRANSCRIPTS 


Your interaction with INTERLISP, from the time you sign on until you logout, is 
known as a session. During the session, you will execute many functions and 
programs. Many times you will want to retain a transcript (e.g., a copy) of your 
session. The transcript records all you type in to INTERLISP and all that it types 
back. (Note: In INTERLISP-D this does not include output from certain user 
packages such as GRAPHER.) 

To initiate transcription, you execute the function DRIBBLE, which takes 
the form 


Function: DRIBBLE 
# Arguments: 2 


Arguments: 1) a file name, FILE 
2) a flag, APPENDFLG 


Value: Previous transcript file name. 


DRIBBLE opens FILE and records what you type in and what INTERLISP 
types out in the file. If FILE is non-NIL, the current transcript, if any, is closed 
and a new one opened. DRIBBLE returns the full name of the previous tran- 
script file. 

To terminate transcription, you can set FILE to NIL. DRIBBLE closes the 
transcript file and returns its full name. No further information is recorded. 

You may make a continuous transcript over several sessions by setting AP- 
PENDFLG to T. Thus, when you resume a session at a later time when FILE 
already exists, new information will be appended to FILE. 

There are two caveats concerning transcript files: 


1. A transcript file does not appear in the list of files that are returned by 
OPENP because it ‘‘shadows’”’ your interaction with INTERLISP. 

2. A transcript file will not be closed by either CLOSEALL or CLOSEF for 
the same reason. Only DRIBBLE can close a transcript file. 


Obtaining the Current Dribble File Name — 
In some programs, you may want to switch among transcript files depending on 
the current task you’re working on. To do so, you need to know the current 
transcript file name. DRIBBLEFILE returns the name of the current transcript 
file. It takes no arguments. 

The following function suggests a way to do this switching: 


(DEFINEQ 

(select-transcript-file (task) 
(COND 

( (EQUAL (DRIBBLEFILE) 
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(task-transcript-file task) )) 
r 
(SELECTQ task 
(<task-id1 
(DRIBBLE (task-transcript-file task) T)) 


(PROGN 
‘5 (DRIBBLE NIL))))) 


where TASK-TRANSCRIPT-FILE is your function to determine the name of 
the transcript file associated with the particular task. Note that each time you 
open the transcript file associated with the task you append new information to 
it. 

Using this approach, you must define the names of the transcript files asso- 
ciated with each task at the beginning of your session. At the end of the session, 
you must be sure to close the current transcript file. 


29.5 GREETINGS 


You may personalize your INTERLISP environment in several different ways. 
One way is to set up a greeting for yourself or other users. Greetings are stored in 
a file INIT.LISP that resides in your directory. 

When INTERLISP is initiated, it looks for two INIT files: 


1. The first INIT file is looked for in the LISP directory. It is usually a site- 
specific profile that supports mutiple users at a site. 


2. The second INIT file is a user-specific file. It contains expressions that 
tailor your environment. It should be located in your directory. 


INTERLISP loads the respective INIT files, if found, and executes the ex- 
pressions contained therein (see Section 29.6). 
INTERLISP prints a greeting using the value of FIRSTNAME which should 


be set in your INIT file via 
(INITVARS (FIRSTNAME ''Steve"’) ) 


or 
(E (SETQ FIRSTNAME 'Steve"’)) 


Changing the Greeting ; 
You can change the form of the greeting in two ways. First, you may define your 


own function, GREET, which is invoked by INTERLISP when you logon. Your 
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definition, which should be loaded via LOAD or defined by DEFINEQ in your 
INIT file, will replace the standard greeting displayed by INTERLISP. 

Second, you can specify greetings for specific dates by modifying the vari- 
able GREETDATES. GREETDATES is a list of elements of the form (<dates- 
tring) . <string>). New entries may be added to GREETDATES by including 
expressions of the following form in your INIT file: 


(ADDVARS (GREETDATES (CONS <string1) <string2)))) 


(ADDVARS (GREETDATES (CONS "25-DEC" "Merry Christmas") )) 
(ADDVARS (GREETDATES (CONS ''16-OCT" "Happy Birthday") )) 


29.6 DIRECTORY ACCESS FUNCTIONS 


Most of your files will reside in a directory which is a collection of files belonging 
to a single user or project. At any time, you are connected to one directory al- 
though you may access files in many other directories by prepending the direc- 
tory name to the file name. INTERLISP provides a number of functions for ac- 
cessing directories from within INTERLISP. 


29.6.1 Reading the File Directory 


You may read the file directory of the external disk using FILDIR, which takes 
the form 


Function: FILDIR 

# Arguments: 1 

Argument: 1) a file group specification, FILGROUP 

Value: A list of files matching the 
specification. 


FILDIR reads the current directory on the external disk and returns a list of 
files that match the file group specification. The value of FILGROUP depends 
on the file name representation used by the operating system. 


«-(FILDIR '*.DCOM) 
( [DSK]BROWSER.DCOM;1 [DSK]HISTMENU.DCOM;1 
[DSK]MAKEGRAPH.DCOM;1  [DSK]UTILPROC.DCOM;1) 

which locates all files having the extension “.DCOM”. , 


29.6.2 Manipulating File Directories 
You may manipulate a file directory using DIRECTORY, which takes the form 
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Function: DIRECTORY 
# Arguments: 4 


Arguments: 1) a files specification, FILES 
2) a set of commands, COMMANDS 
3) a default text » DEFAULTEXT 
4) a default version, DEFAULTVER 


Value: A list of all files that satisfy the 
commands given to DIRECTORY. 


FILES is a files specification that identifies the files to be operated upon. It 
may take one of three forms: 


1. NIL, whence the form *.*;* is assumed meaning all files. 

2. An atom containing <ESC)s or *s which match any number of charac- 
ters or ?s which match a single character. 

3. A list of one the forms 


(<files) + <files)) "and" 
(<files) -— <files)) "and not" 
(<files) * <files)) "or" 


For example, (T$ + $L) will match any file name in the directory that be- 
gins with T or ends in L, while (TS — *.DCOM) will match all files that begin 
with T and are not .DCOM files. 

For each file that matches, the commands in COMMANDS are executed. 
The available commands are 


P Print the file name 

PP Print the file name (except the version 
number) 

(string) Print the string 

READDATE Print the appropriate information 

WRITEDATE returned by GETFILEINFO (see Section 

CREATIONDATE 16.4) 

SIZE 

LENGTH 

BYTESIZE 

PROTECTION 

AUTHOR 


TYPE 
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COLLECT 


COUNTSIZE 


PAUSE 


PROMPT <message) 


OLDERTHAN <n) 


OLDVERSIONS <n) 


BY <user) 


DELETED 


OUT <file> 


COLUMNS <n) 


TRIMTO <n) 


DELETE 


UNDELETE 


The value returned by DIRECTORY will be 
a list of file names; add the complete 
file name to this list. 


The value of DIRECTORY will be a sum; 
add the size of this file to that sum. 


Wait until the user types a character 
before proceeding with the rest of the 
commands; this allows you to display 
some information and think about it. 


Prompt the user with <message). If he 
responds NO, abort command processing 
for this file. 


Continue command processing if the file 
hasn't been referenced in N days. 


Continue command processing if there are 
at least N more recent versions of the 
same file. Usually, this ensures that 
you have an adequate audit trail for the 
file within the directory. Used 
primarily with DELETE. 


Continue command processing if the file 
was written by a specified user. 


Examine files that are marked deleted 
within the directory as well. 


Print the results to the specified 
output file. 


Attempt to format the output in N 
columns, rather than just 1. 


Delete all but N versions of the file; N 
must be greater than or equal to 0. 


Delete the file. If this command is 
specified without COLLECT, the value of 
DIRECTORY will be NIL; otherwise, a list 
of files deleted. 


Undeletes the indicated files that have 
just been deleted. 


Consider the following examples: 
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«(DIRECTORY '<LISPUSERS)*.COM 'PP) 


« LISPUSERS) 
ALL.COM 
ARITHDECLS.COM 
ARITHMAC .COM 
BQUOTE.COM 
CHARCODE .COM 
CHAT .COM 


«(DIRECTORY '<{LISPUSERS)S$.* '(PP SIZE) ) 


«LISPUSERS) 
SAMEDIR. 2 
SAMEDIR.COM 0 
SAMEDIR.TTY 2 
SCRATCHLIST. 0 
SCRATYCHLIST.COM 0 
SCREENOP. 28 
SCREENOP . COM 29 
SCREENOP . TC 14 
SCREENOP . TCD 12 
SCREENOP . TTY 2 


DIRECTORY uses DIRCOMMANDS to correct spelling and to define syn- 
onyms and abbreviations for commands. The structure of DIRCOMMANDS is 


<(PRINTDEF DIRCOMMANDS) 

((- . PAUSE) 

(AU . AUTHOR) 

BY COLLECT (COLLECT? PROMPT " ? " COLLECT) 
COUNTSIZE 

(DA . WRITEDATE) 

(DEL . DELETE) 

(DEL? . DELETE?) 

DELETE 

(DELETE? PROMPT "delete? ' DELETE) 
DELETED 

(LE LENGTH '"(' BYTESIZE ")") 

(OBS . OLDVERSIONS) 

OLDVERSIONS 

(OLD OLDERTHAN 90) 

OLDERTHAN 

(OU . OUT) 
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OUT P PAUSE (PR . PROTECTION) 

PROMPT 

(SI . SIZE) 

(TI . WRITEDATE) 

UNDELETE 

(VERBOSE AUTHOR CREATIONDATE SIZE READDATE WRITEDATE) ) 


29.6.3 Connecting to Another Directory 


You will note in the examples above that I had to specifically provide an alterna- 
tive directory name that I wanted to inspect. You may connect to a directory 
(i.e., make it your current directory) using CNDIR, which takes the form 


Function: CNDIR 
# Arguments: 2 


Arguments: 1) the directory name, DIRNAME 
2) the directory password, PASSWORD 


Value: The name of the old directory. 


Under INTERLISP-10, CNDIR resides in the LISPUSERS package EXEC- 
-COM. You must load that package first in order to execute CNDIR. Consider 
the following example: 


<-(LOAD '<{LISPUSERS) EXEC .COM) 

« LISPUSERS) EXEC .COM.54 

FILE CREATED 13-JUN-82 15:27:46 

collecting arrays 

1071, 10287 free cells 

EXECCOMS 

« LISPUSERS ) PASSWORDS .COM.15 

compiled on 6-FEB-82 20:19:30 

FILE CREATED 6-FEB-82 20:19:17 

PASSWORDSCOMS 

< LISPUSERS ) EXEC .COM.54 

«<-(CNDIR 'LISPUSERS) 

PS:<LISPUSERS) (password) "I don't know the password so I 
just type a carriage return" 


Can't connect to directory 


If a password is associated with a directory and is not provided in the call to 
CNDIR, you will prompted for the password. 
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<(CNDIR) 
PS: <KAISLER) 


If DIRNAME is NIL, CNDIR just prints the name of your current directory. 


29.7 STORAGE MANAGEMENT 


INTERLISP eases the burden of storage management by doing dynamic allocation 
for various datatypes on demand as you create new objects. In INTERLISP-D, 
you usually do not have to worry about how much storage you have, because 
garbage collection is performed on an incremental basis. However, when pro- 
grams get very large and complex, you may find that you have to sacrifice one 
type of storage in order to accommodate more objects of another type. This situ- 
ation occurs because INTERLISP divides available memory into a number of 
pools associated with different object types. When a pool is exhausted, it may be 
increased from an available space pool. 


29.7.1 Displaying Storage Usage 


STORAGE provides you with a description of storage usage within the IN- 
TERLISP environment. It takes the form 


Function: STORAGE 
# Arguments: 0 
Arguments: N/A 
Value: NIL 


The “‘actual’’ value of STORAGE is a formatted listing that is written to the 
primary output file. 

The following example is taken from the Fugue release running on a Xerox 
1100 Scientific Information Processor. 


< (STORAGE) 
Type Assigned Free In Total Pages 
Items Use Allocations (items) 
FIXP 20 2560 1752 808 26271 
FLOATP 14 1792 537 1255 1577 
LISTP 1512 175392 1419 137973 578679 
ARRAYP 8 512 326 186 10527 
STRINGP 68 4352 119 4233 7080 


STACKP 4 512 504 8 1894 
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VMEMPAGEP 106 106 3 103 104 
STREAM 6 33 14 19 19 
FDEV 6 24 5 19 19 
IMAGEOPS 

BitBltTable 

TERMTABLEP 

READTABLEP «more numbers) 

CHARTABLE 

IOFILEINFOBLK 

BUFFER 

PROCESS 

PROCESSQUEUE 

EVENT 

MONITORLOCK 

SYSQUEUE 


TOTAL 1910 


Data Spaces Allocated Remaining 
Pages Pages 


MDS 1910 1674 
Atoms 82 46 
Print Names 507 1541 
Arrays 2817 4095 
NIL 


29.7.2 Gaining Space 


When your program gets too large, INTERLISP will start to complain. The na- 
ture of its complaint depends on the implementation. INTERLISP-D stores its 
virtual memory on the integral disk of the Xerox 1100 Scientific Information 
Processor. When the initial allocation (which Xerox recommends to be contigu- 
ous space) is exhausted, INTERLISP grabs the largest remaining chunk of free 
contiguous space that it can find. This is known as a segment of the virtual mem- 
ory file. Since segments are disconnected, performance tends to degrade rapidly. 
At some point, an internal decision is made that there are too many segments. 
INTERLISP warns you that you must reconfigure your system (particularly your 
virtual memory file) before it can continue. You are given a certain grace period 
in which some curative steps may be taken. 

GAINSPACE is a function that interacts with you to remedy the problem of 
exhausted space. You probably should treat it as the method of last result be- 
cause the actions it takes are generally disruptive of the environemt—by that, I 
mean that it disables considerable subsystems of INTERLISP in order to give 
you the space that you require. 
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GAINSPACE takes the following form 


Function: GAINSPACE 
# Arguments: 0 
Arguments: N/A 
Value: NIL 


When it is invoked, it conducts a dialogue with you to determine what fea- 
tures you are willing to give up. The side effect of GAINSPACE is to reclaim 
storage space through several rather drastic measures. It is usually wise to exe- 
cute STORAGE after running GAINSPACE to determine what has happened. 


 (GAINSPACE) 

erase current Masterscope database? Yes 

discard HPRINT initialization? Yes 

purge History lists? Yes 

discard definitions on property lists? Yes 

discard old values of variables? Yes 

erase properties? No 

erase CLISP translations? Yes 

erase system hash array? Yes 

discard context of last edit? Yes 

discard information saved for undoing your greeting? Yes 
erase filepkg information? No 

mapatoms called to erase the indicated properties...done 


GAINSPACE uses the list GAINSPACEFORMS to drive its dialogue. Each 
entry on GAINSPACEFORMS has the format 


(<precheck) <message) <form) (keylst)) 


PRECHECK is evaluated. If it returns NIL, GAINSPACE skips to the next 
entry. Otherwise, ASKUSER (see Section 14.7) is called with MESSAGE and 
the optional KEYLST. If the user responds N (the “‘o” is filled out by IN- 
TERLISP), i.e., ASKUSER returns N, GAINSPACE moves to the next entry. 
Otherwise, it evaluates FORM with RESPONSE bound to the value returned by 
ASKUSER. 

GAINSPACEFORMS has the following value: 


( (MSDATABASELST 
"erase current Masterscope database" 
(% . ERASE) ) 
((OR HPRINTHASHARRAY HPRINTRDTBL) 
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"discard HRPINT initialization'"' 
(PROGN 
(CLRHASH HPRINTHASHARRAY) 
(SETQ HPRINTHASHARRAY (SETQ 
HPRINTRDTBL) ) ) ) 
((CAR LISPXHISTORY) 
"purge history lists" 
(PURGEHISTORY RESPONSE) 
((Y Neg!) 
(N Nott) 
(E "verything") )) 
(T 
"discard definitions on property lists"! 
(SETQ SMASHPROPSLST1 
(CONS 'EXPR 
(CONS 'CODE 
(CONS 'SUBR 
SMASHPROPSLST1) ) ) ) ) 
(T 
"discard old values of variables" 
(SETQ SMASHPROPSLST1 
(CONS 'VALUE SMASHPROPSLST1) ) ) 
(T 
"erase properties" 
(ERASEPROPS RESPONSE) 
((Y Nag! 
EXPLAINSTRING 
"Yes—you will be asked which properties are 
to be erased" 
(N Nott) 
(A myyt 
CONFIRMFLG T EXPLAINSTRING 
"All-all properties mentioned on 
SMASHPROPSMENU'"' ) 
(E "ait : 
EXPLAINSTRING 
"Edit-you will be allowed to edit a list of 
property names") ) ) 
(CLISPARRAY 
"erase CLISP translations" 
(CLRHASH CLISPARRAY) ) 
( CHANGESARRAY 
"erase changes array" 
(CLRHASH CHANGESARRAY) ) 
(SYSHASHARRAY 
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"erase system hash array"! 
(CLRHASH) ) 

((GETPROP 'EDIT 'LASTVALUE) 
"discard context of last edit" 
(REMPROP "EDIT "LASTVALUE) ) 

(GREETHIST 
"discard information saved for undoing your 
greeting" 

(SETQ GREETHIST) ) 

(FILELST 
"erase filepkg information" 
(CLEARFILEPKG RESPONSE) 

((Y Neg!) 
(N Not) 
(E "verything' ) 
(F "ilemaps only") ))) 


SMASHPROPSMENU has the following form: 


(("old values of variables" 
VALUE) 
("function definitions on property lists" 
EXPR CODE) 
("advice information" 
ADVISED ADVICE READVICE 
(SETQ ADVISEDFNS NIL)) 
("filemaps" 
FILEMAP) 
("lisp information (warning: this will disable 
clisp!)" 
ACCESSFN BROADSCOPE CLISPCLASS CLISPCLASSDEF 
CLISPFORM 
CLISPIFYISPR CLISPINFIX CLISPISFORM CLISPISPROP 
CLISPNEG CLISPTYPE CLISPWORD CLMAPS I.S.OPR 
I.S.TYPE LISPFN SETFN UNARYOP) 
("compiler information (warning: this will disable 
the compiler!)"' 
AMAC BLKLIBRARYDEF CROPS CTYP GLOBALVAR MACRO 
MAKE OPD UBOX) 
("definitions of named history commands" 
*HISTORY*) 
("context of edits exited via save command" 
EDIT-SAVE) ) 


“rr 


30 





The INTERLISP 
Execution Environment 


INTERLISP is based on the principle of the stack or pushdown list. Each func- 
tion is allocated a frame on the stack when the function is invoked. The frame 
establishes the environment of the function, namely, its local variable bindings 
and argument values, if any. INTERLISP provides many low-level functions for 
inspecting and manipulating the stack. 


Caution: 

Only sophisticated users should attempt to manipulate the stack. Erroneous 
changes to the stack can destroy your computation’s environment and erase all 
the work you have done. 


30.1 BINDING OF VARIABLES 


Many schemes have been used to bind values to variables. INTERLISP uses one 
of two different schemes depending on the implementation you are using: 


Shallow Binding 

Values for variables are stored in value cells associated with the variable name. 
When a function is entered, the variables it uses are rebound. Values stored in 
the value cells are stored in a stack frame associated with the function call. 
When the function is exited, each variable must be individually unbound, i.e., 
its values in the stack frame are restored to the value cells. INTERLISP-10, IN- 
TERLISP/370, and INTERLISP-VAX use shallow binding. 


Deep Binding 

When a variable is bound, space is allocated on the stack for the variable name 
and its value cell. The variable’s value is placed in the value cell. When a vari- 
able is accessed, its value is found by searching the stack from the top for the 
most recent occurrence of the variable name. The value is retrieved from the 
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associated value cell. If the variable is not found on the stack, the variable’s top- 
level value cell is accessed for the value. INTERLISP-D uses deep binding. 


30.1.1 Variable Types 
INTERLISP supports three types of variables: 


LOCALVARS 

A local variable is one that is used within a function, LAMBDA/NLAMBDA 
expression, or a PROG. The variable’s binding exists only for the duration of the 
function’s or PROG’s execution. 


GLOBALVARS 

A global variable is a “‘free’’ variable, e.g., one that has not been bound by any 
function. Its binding is always stored in the top-level value cell of the atom. The 
variable’s binding exists for the duration of your sysout. 


SPECVARS 

A special variable is a variable referenced in a function that was bound in an- 
other function or bound globally. Basically, it means the variable is bound out- 
side the function but is visible within the function. The difference between 
SPECVARS and LOCALVARS mainly has to do with how the variables are ac- 
cessed. 


30.1.2 Global Variables 
Global variables may be specified in INTERLISP in two ways: 


1. Putting the variable name on the GLOBALVARS list 
2. Putting the property GLOBALVAR with value T on the variable’s prop- 
erty list. 


Global variables are always accessed via their top-level value when they are 
used freely in a function (using GETTOPVAL—see Section 3.9.2). Values are 
assigned to global variables using SETTOPVAL even when SETQ is invoked by 
your program. 

INTERLISP-D uses a deep-binding scheme while INTERLISP-10/VAX/ 
370 all use a shallow-binding scheme. In deep-binding, references to variables 
use the nearest binding for the variable in the stack to the function where the 
variable is referenced. If the variable is passed as an argument to the function, 
then it is bound in the function’s stack frame. Otherwise, it is used freely and 
INTERLISP must search the stack for the binding. Searching may be expensive 
if the nesting of function calls is extensive. To circumvent the searching you may 
use global variables to provide more efficient access to the variable’s value. 
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In a shallow-binding scheme, no distinction is made between global vari- 
ables and other variable types. All variable references access the variable’s value 
cell. Access to a variable’s value is always independent of the depth of the stack. 

INTERLISP-10/VAX/370 run on general-purpose computers which usu- 
ally have instructions conducive to executing conventional languages such as 
FORTRAN. In fact, the DECSystem-10 and IBM 370/308x/43xx series ma- 
chines do not have hardware stack support, so shallow binding provides a 
greater measure of efficiency. On the other hand, INTERLISP-D runs on the 
custom-built Xerox 11xx Scientific Information Processors which provide en- 
hanced hardware stack support mechanisms. 

Global variables are treated like SPECVARS when function are compiled. 
That is, their names are always placed on the stack when they are rebound. 

INTERLISP treats all system parameters, unless otherwise specified, as 
global variables. Rebinding these variables in a deep-binding scheme does not 
affect the behavior of the system because that binding will be placed in a func- 
tion’s stack frame. To affect the system’s behavior, you must use RESETVAR 
(see Section 25.7.3) to establish a new value. 


30.2 STACK STRUCTURE 


A stack is a pushdown list. A discussion of stack algorithms may be found in 
[knut68]. INTERLISP uses a stack structure known as a spaghetti stack which is 
described in [bobr73a]. A detailed discussion of the INTERLISP-10 stack mech- 
anisms at the virtual machine level may be found in [moor79]. 


30.2.1 A Basic Frame Example 


Using BTV! in the Break Package, we can display the basic frame of the func- 
tion MAKESLOT as it appears under INTERLISP-D (Fugue release) when the 
function is newly broken. The data are taken from a Xerox 1100 Scientific Infor- 
mation Processor. 


(MAKESLOT broken) 


:BTV! 

Basic frame at 40174 

40160: 0 51655 NODE TEXAS 

40162: 0 52021 SLOT CAPITOL 

40164: 0 15071 INHERITANCE.TYPE IS 
40166: 0 113 METHOD S 

40170: 0 51513 ¥local* MAKESLOT 
40172: 0 0 [padding] 

40174: 100400 40160 
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30.2.2 A Frame Extension Example 


A frame extension is a variable-length block of storage containing 


a frame name 


a pointer to variable bindings, BLINK 


pointers to other frame extensions, ALINK/CLINK 
temporary variables 
reference counts 


BTV! also prints the contents of the frame extension for MAKESLOT as 


shown below: 


Frame xtn at 40176 frame name = MAKESLOT 


40176: 
40200: 
40202: 
40204: 
40206: 
40210: 
40212: 
40214: 
40216: 
40220: 


40222: 


40224: 
40226: 
40230: 
40232: 
40234: 
40236: 
40240: 
40242: 


40264: 
40266: 
40270: 
40272: 
40274: 
40276: 
40300: 
40302: 
40304: 


141002 
103524 
40332 
40300 
177777 
16 

0 

16 

16 

4 


10 


16 
16 
16 
0 
0 
0 
0 
x By A Ned 
through 
177777 
177777 
0 
0 
177776 
177763 
0 
0 
0 


40130 
20040 
412 
13427 
0 

5 
51513 
4 

4 
135406 


135272 


0 

10 

15 
15714 


oo°0o°o 


30 

0 

0 

5 beg Be 


[V, USE=2, alink] 

{fn header] 

[next, pe] 

[nametable ] 

[blink, clink] 

*local* 5 

*¥local* MAKESLOT 
¥local* 4 

¥local* 4 

¥local* (LAMBDA ...) 
[definition of MAKESLOT] 
*local* (NODE SLOT 
INHERITANCE.TYPE METHOD) 
¥local* 0 

*¥local* 8 

¥local* 13 

*local* METHOD 

*¥local* NIL 

*¥local* NIL 

¥local* NIL 


¥local* [unbound] 


*¥local* [unbound] 
[padding] 
[padding] 
[padding] 


NIL 
NIL 
MAKESLOT 
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40306: 10 13400 ([]#0,77400, []#60, 174060) 
40310: 13621 51604 
40312: 51547 15714 


40314: 0 0 NIL 

40316: 0 0 NIL 

40320: 0 1 NOBIND 

40322: 2 3 [VMEMPAGE] #2, 3 
40324: 0 0 NIL 

40326: 0 0 NIL 

40330: 0 0 NIL 

MAKESLOT 


Two frame extensions may point to the same basic frame which allows two 
processes to communicate via shared variable bindings. 


30.2.3 Stack Frames and Pointers 


A stack is composed of frames which are allocations of storage to hold the values 
of local variables during computation. Coupled with frames are a data structure 
known as the frame extension. It is a variable-sized block of storage that con- 
tains 


a frame name 

a pointer to some variable bindings, BLINK 
an access chain pointer, ALINK 

a control chain pointer, CLINK 

other implementation dependent information 


Both ALINK and CLINK point to other frame extensions. 

A frame extension completely specifies the variable bindings and control 
information necessary to evaluate a function. 

At any instant, only one function is being executed. Thus, one frame will be 
distinguished as having control of the central processor. This frame is called the 
active frame. Initially, the top-level frame, which is hardwired into the inter- 
preter, is the active frame. When a computation in an active frame invokes an- 
other function, a new basic frame and frame extension are built on the stack. 
The frame of the new basic frame will be the name of the function that is being 
invoked. The ALINK, BLINK, and CLINK fields of the new frame will be as- 
signed values depending on the calling sequence to the function. The function is 
“run” by passing control to the new frame. 

The chain of frame extensions that may be reached via the ALINK is called 
the access chain of the frame. The first frame in the access chain is the starting 
frame. The chain through successive CLINKs is called the control chain. 

When an active computation has been completed in a frame, control usually 
returns to the frame pointed to by the CLINK. The frame in the CLINK becomes 
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the active frame. Thus, control of the computation is passed through the control 
chain. It can be said to reflect the progress of the computation. Tracing func- 
tions is effectively a process of backtracking through the control chain. 

When a frame is exited, the storage associated with the basic frame and the 
frame extension may be reclaimed. You may hold on to a frame by creating a 
stack pointer to it. A stack pointer contains the address of the frame. This allows 
you to run other computations using that frame as an environment. 

Stack pointers print in different formats, depending on the version of IN- 
TERLISP that you are running. They are returned by many of the stack func- 
tions described in the following sections. As long as a stack pointer has been 
allocated to a frame, that frame will not be garbage collected. Two stack 
pointers referencing the same frame are not necessarily EQ, but are EQP. 

Allocating a stack pointer may consume a large amount of stack space. The 
space is not freed, even if it is no longer being used, until the next garbage collec- 
tion. Thus, if you are using stack pointers rather vigorously, you may want to 
invoke garbage collection at opportune times during your computation. 

If there is insufficient stack space to allocate a new frame, a STACK OVER- 
FLOW condition will occur. Usually, there is not much you can do but reset the 
environment. Note that stack overflows may occur when you have runaway func- 
tions, particularly ones that are recursive. 


30.3 STACK ACCESS FUNCTIONS 


You may access the stack using the functions described in this section. Each 
stack function takes an argument which describes the stack frame that you want 
to access. The frame may be specified by 


a frame name (e.g., MAKESLOT) 


NIL, indicating the active frame (which is the stack frame of the stack 
function itself) 


T, the top-level frame 
a literal atom, which is equivalent to (STKPOS <atom) -1) 
a number, which is equivalent to (STKNTH number) 


Two additional errors may occur: 


ILLEGAL STACK ARG 
When a stack frame descriptor is expected and the argument supplied is not one 
of the above. Alternatively, if there is no frame corresponding to the argument. 


STACK POINTER HAS BEEN RELEASED 
When a released stack pointer is supplied as a stack frame descriptor for any 
purpose other than reuse. 
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The following functions convert names and numbers to pointers and names. 
They might be summarized as follows: 


TO 
Function Name Stack Pointer 
FROM 
Function Name N/A STKPOS 
Numbers STKNTHNAME STKNTH 
Stack Pointer STKNAME N/A 


30.3.1 Locating a Stack Frame 


STKPOS allows you to locate a stack frame by its name. It takes the form 


Function: STKPOS 
# Arguments: 4 


Arguments: 1) a frame name, FRAMENAME 
2) an integer, N 
3) an initial position. IPOSITION 
4) an old stack pointer, OPOSITION 


Value: A stack pointer to the frame; 
otherwise, NIL. 


STKPOS searches the stack for the Nth frame having the same name as 
FRAMENAME. If N is NIL, a —1 is assumed. The search begins at IPOSI- 
TION, which is a stack frame, and proceeds as follows: 


along the control chain if N is negative 
along the access chain if N is positive 


If OPOSITION is non-NIL and is a stack pointer, it is re-used. 

STKPOS is a generalized positioning algorithm. Argument N allows you to 
select the Nth of many similar frames. This feature is useful when you are 
searching the stack environment of a recursive function (a new frame is created 


for each recursive call), e.g., 


«-(STKPOS 'MAKESLOT) 
#1,13446/MAKESLOT 
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You are not allowed to create a stack pointer to the active stack frame. 
Thus, 


«(STKPOS 'STKPOS) 
ILLEGAL STACK ARG 


Locating a Frame by Position 

You may also locate a frame by providing its index from the top of the stack 
(which is the most recent function invocation). STKNTH takes the following 
form 


Function: STKNTH 


# Arguments: 3 


Arguments: 1) an integer, N 
2) an initial position, IPOSITION 
3) an old position, OPOSITION 


Value: A stack pointer to a frame or NIL. 


STKNTH returns a stack pointer to the Nth frame from the top of the stack 
or, if IPOSITION is non-NIL, from IPOSITION. N is used as follows: 


if N is negative, STKNTH follows the control chain 
if N is positive, STKNTH follows the access chain 
if N is 0, STKNTH returns a stack pointer to IPOSITION 


Consider the following example: 


< (STKNTH) 
ILLEGAL STACK ARG 


because you are trying to create a stack pointer to the active frame which is not 
allowed. 


«(STKNTH 1) 
#1,13452/APPLY 


<(STKNTH 2) 
#1, 13476/LISPX 


because if we look at the stack, which we can inspect with the BT command from 
the Break Package, we see 


(MAKESLOT broken) 
:BT 
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MAKESLOT 
\EVALFORM 
\SAFEEVAL 
BREAK1 
\EVALFORM 
EVAL 
LISPX 
ERRORSET 
EVALQT 


If OPOSITION is supplied and it is a stack pointer, it is reused; otherwise, it 
is ignored. 
30.3.2 Obtaining and Changing the Frame Name 


You may obtain the frame name for a stack position by executing STKNAME, 
which takes the form 


Function: STKNAME 

# Arguments: 1 

Arguments: 1) a stack descriptor, POSITION 
Value: The stack frame name. 


STKNAME returns the name of the stack frame (i.e., the name of the func- 
tion for which the frame was built) for the frame described by POSITION, e.g., 


«(STKNAME 2) 
LISPX 


<(STKNAME 1) 
APPLY 


«<(STKNAME (STKPOS 'MAKESLOT) ) 
MAKESLOT 


because EVALOT is, effectively, an APPLY of LISPX to its inputs that are read 
by low-level LISP functions (See Section 25.2). 


Obtaining the Nth Stack Frame Name 
From an initial position, you may obtain the name of the NTH frame using 


STKNTHNAME. It takes the form 


Function: STKNTHNAME 
# Arguments: 2 
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Arguments: 1) an integer, N 
2) an initial position, IPOSITION 
Value: The name of the stack frame or NIL. 


STKNTHFRAME is equivalent to executing 
(STKNAME (STKNTH N IPOSITION) ) 


but avoids the creation of a stack pointer. Like STKNTH, it returns NIL if there 
are a lesser number of frames in the stack than N. Like STKNTH, it follows the 
control or access chains depending on the sign of N. 


Changing a Stack Frame Name 
You may change the name of a stack frame by executing SETSTKNAME, which 
takes the form 

Function: SETSTKNAME 

# Arguments: 2 


Arguments: 1) a stack position, POSITION 
2) a name, NAME 


Value: The new frame name. 
Unless you are an experienced INTERLISP programmer, you should at- 


tempt to change the name of the stack frame. This function may be used when 
an error occurs. 


30.4 VARIABLE BINDING FUNCTIONS 


Variables appear as entries in a stack frame. You may change the binding of a 
variable or determine the binding using the following functions. 


30.4.1 Obtaining Variables at a Stack Frame 


VARIABLES returns a list of variables that are bound in the stack frame POSI- 
TION. It takes the form 


Function: VARIABLES 

# Arguments: 1 

Argument: 1) a stack frame, POSITION 

Value: The list of variables bound at the stack 


frame described by POSITION. 
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Consider the following example (from INTERLISP-10): 


+ (STKNTH 4) 


[STACKP]#152002/ERRORSET 


“(VARIABLES 4) 


(HELPCLOCK LISPXHIST HELPFLG NIL LISPXLISTFLG LISPXLINE 


NIL 


NIL LISPXVALUE NIL NIL) 


30.4.2 Obtaining Variable Values at a Stack Frame 
STKARGS returns the values of the variables bound at POSITION. It takes the 


form 
Function: 
# Arguments: 
Argument: 


Value: 


STKARGS 
a 
1) a stack frame, POSITION 


A list of argument values. 


Consider the following example (from INTERLISP-10): 


<-(STKARGS 'ERRORSET) 


((DUMMY) T NIL) 


30.4.3 Scanning the Stack for Bindings 


When you are executing a complex program, your function nesting may become 
very deep. Within this nesting, some variables will be used freely while others 
will be bound from one function to another. If a function breaks, you may not 
know where a free variable is bound. STKSCAN searches the stack looking for a 
binding of a specified variable. It takes the form 


Function: 
# Arguments: 
Arguments: 


Value: 


STKSCAN 
3 


1) a variable name, VAR 
2) an initial stack frame, IPOSITION 
3) an optional stack pointer, OPOSITION 


A stack pointer to the frame in which VAR 
is bound; otherwise, NIL. 


STKSCAN searches the stack from the stack descriptor specified by IPOSI- 
TION looking for a frame in which VAR is bound. Consider the following exam- 


ple: 
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*+(STKSCAN 'X) 
[STACKP]#152734/FACTORIAL 


«(STKSCAN 'X 10) 
[STACKP]#152731/FACTORIAL 


<(STKSCAN 'X 8) 
[STACKP]#152730/FACTORIAL 


which shows that the variable X is bound in several frames on the stack as one 
would expect from a recursive function. 
The stack appears as (using BTV) 


COND 
X 0 
FACTORIAL 
COND 
X 1 
FACTORIAL 
COND 
X 2 
FACTORIAL 
COND 
X 3 
FACTORIAL 
COND 
X 4 
FACTORIAL 
EVAL 
LISPXVALUE NIL 
LISPXLINE NIL 
LISPXLISTFLG T 
HELPFLG T 
(LISPXHIST ((&) _) 
HELPCLOCK 10641 
*PROG*LAM 
LISPXID < 
LISPX 
ERRORSET 
EVALQT 


We will use this stack formation in examining the effect of several other 
stack functions in the following sections. 


30.5 STACK FRAME OPERATIONS 


INTERLISP provides considerable flexibility for manipulating the contents of 
stack frames. The caveat remains: Let the user beware! You may do your envi- 
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ronment grievous damage by manipulating the contents of stack frames from 
within your program. 


30.5.1 Distinguishing Real from Dummy Frames 


INTERLISP-10 places dummy frames on the stack as placeholders for certain 
types of functions including *PROG*LAM, *ENV*, and some block compiler 


entities. You may test if a frame is a dummy frame using DUMMYFRAMEP, 
which takes the form 


Function: DUMMYFRAMEP 

# Arguments: 1 

Argument: 1) A stack frame pointer, POSITION 
Value: T, if the frame is a dummy frame. 


DUMMYFRAMEP determines if there is a link to the frame at POS, e.g., if 
your program contains a function call to the function that the frame represents. 
The types of frames mentioned above merely serve to establish environmental 
information and are never explicitly executed. Dummy frames are used primar- 
ily during interpretation and disappear when functions are compiled. 

Consider the stack described above: 


< (DUMMYFRAMEP '*PROG*LAM) 

T 
because *PROG*LAM is placed on the stack as a marker by INTERLISP-10, 
but 

<(DUMMYFRAMEP 'FACTORIAL) 

NIL 

«(DUMMYFRAMEP 'COND) 

T 


Testing for a Real Frame 
An alternative function, REALFRAMEP, tests whether a stack frame is a real 


frame, i.e., not a dummy frame. It takes the form 


Function: REALFRAMEP 
# Arguments: 2 


ments: 1) a stack pointer, POSITION 
Mee 2) an interpretation flag, INTERPFLG 
Value: POSITION, if the frame does not disappear 


when the function is compiled. 
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<(STKNAME 32) 
COND 


< (REALFRAMEP 6 T) 
6 


«<—(REALFRAMEP 6) 
NIL 


because, when the function is compiled, the stack frame representing COND 
disappears. INTERPFLG specifies whether the determination should be made 
in interpreted or compiled mode. 

Note: Neither of these functions is available in INTERLISP-D because of 
the different mechanisms used for representing and manipulating the stack. 


30.5.2 Finding a Real Stack Frame 


Given that dummy and real stack frames may be intermixed on the stack, during 
debugging you may want to find a real stack frame that is linked somewhere 
below your present position. REALSTKNTH allows you to skip back N frames 
from the current position. It takes the form 


Function: REALSTKNTH 
# Arguments: 4 


Arguments: 1) a frame count, N 
2) a stack pointer, POSITION 
3) an interpretation flag, INTERPFLG 
4) an old stack pointer, OLDPOSITION 


Value: A stack pointer to the Nth frame. 


REALSTKNTH operates like STKNTH, including taking the same type of 
arguments, except that it applies REALFRAMEP to each frame that it exam- 
ines on the stack. Only those frames that satisfy REALFRAMEP with IN- 
TERPFLG are counted against N. If N is negative, the control chain from POSI- 
TION is followed. If N is negative, the access chain is followed. 


30.5.3 Scanning Frames for Atom Bindings 


An atom may be rebound several times when a program is executed. As each 
function is invoked and the atom passed as an argument or the atom name is 
reused as a local variable within a function, the atom’s name will be rebound on 
the stack in the frame corresponding to that function invocation. You. may 
search the stack for a particular atom binding using FRAMESCAN, which takes 
the form 
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Function: FRAMESCAN 
# Arguments: 2 
Arguments: 1) an atom name, ATM 
2) a stack pointer, POSITION 
Value: The relative position of the binding of 


ATM in the basic frame of POSITION. 


Consider the following example: 


«-(FRAMESCAN 'X 'FACTORIAL) 
4 


«-(FRAMESCAN 'HELPFLAG '*PROG*LAM) 
3 


FRAMESCAN returns NIL if the variable is not bound in the frame speci- 
fied by POSITION. 


30.6 EVALUATION IN OTHER FRAMES 


The purpose of a stack pointer is to allow you to preserve an evaluation environ- 
ment for later usage and inspection. Each stack frame contains bindings for 
variables that provide a context for evaluation. INTERLISP provides a set of 
functions that allows you to evaluate functions in stack frames (i.e., contexts) 
other than the current active frame. This feature is extremely useful during de- 
bugging. It should be utilized only by experienced INTERLISP programmers. 


30.6.1 Evaluation in Other Contexts 


ENVEVAL allows you to evaluate an expression in another environment. It 
takes the form 


Function: ENVEVAL 


# Arguments: 5 


Arguments: 1) an expression, EXPRESSION 
2) an access chain pointer, APOSITION 
3) a control chain pointer, CPOSITION 
4) an ALINK release flag, AFLAG 
5) a CLINK release flag, CFLAG 


The value of the expression when evaluated 
in the new context. 


Value: 


ENVEVAL creates a new active frame on the stack for EXPRESSION using 
the frame specified by APOSITION as its ALINK and the frame specified by 
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CPOSITION as its CLINK. Note that APOSITION and CPOSITION specify a 
sequence of frames that will describe the bindings for variables within EXPRES- 
SION. AFLAG and CFLAG, if non-NIL, specify that APOSITION and CPOSI- 
TION, respectively, will be released after EXPRESSION is evaluated. 


Applying a Function in an Environment 
An alternative form, ENVAPPLY, applies a specified function to the given argu- 
ments within the new context. It takes the form 


Function: ENVAPPLY 
# Arguments: 6 


Arguments: 1) a function name, FN 
2) an argument list, ARGS 
3) an access chain pointer, APOSITION 
4) a control chain pointer, CPOSITION 
5) an ALINK release flag, AFLAG 
6) a CLINK release flag, CFLAG 


Value: The value returned by FN when applied to 
ARGS in the specified context. 


30.6.2 Evaluating Expressions in an Access Environment 


You may evaluate expressions in an access environment using the functions 
STKEVAL and STKLAPPLY. STKEVAL takes the form 


Function: STKEVAL 
# Arguments: 3 
Arguments: 1) a stack descriptor, POSITION 


2) an expression, EXPRESSION 
3) a release flag, FLAG 


Value: The value of EXPRESSION when evaluated ‘in 
the specified context. 


STKEVAL may be defined as 


(DEFINEQ 
(stkeval (position expression flag) 
(ENVEVAL expression position NIL flag) 


)) 


An alternative form, STKAPPLY, operates in a manner similar to 
STKEVAL, but applies a function to some arguments. It takes the form 


Function: 
# Arguments: 
Arguments: 


Value: 
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STKAPPLY 
4 


1) a stack descriptor, POSITION 
2) a function name, FN 

3) an argument list, ARGS 

4) a release flag, FLAG 


The value returned by the function when 
applied to the arguments in the specified 
context. 


STKAPPLY may be defined as 


(DEFINEQ 


(stkapply (position fn args flag) 
(ENVAPPLY fn args position NIL flag) 


)) 


In both functions, if FLAG is non-NIL, the stack descriptor will be released 
after the evaluation is performed. 


30.7 MANIPULATING STACK POINTERS 


A stack pointer is the address of a basic stack frame in the stack. Stack pointers 
are used by these functions to reference the basic stack unit, the frame. Stack 
pointers represent a unique data type because they are allocated from a special 
memory pool. INTERLISP provides a number of functions for manipulating 


these pointers. 


30.7.1 Testing a Stack Pointer 


You may test the value of an atom to determine if it is a stack pointer using 
STACKP, which takes the form 


Function: 
# Arguments: 
Argument: 


Value: 


STACKP 
1 
1) a stack pointer, POSITION 


POSITION, if it is a stack pointer; 
otherwise, NIL. 


Consider the following example: 


:(SETQ XSTKP (STKPOS (STKNAME 21))) 
[STACKP]#152632/FACTORIAL 
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:(STACKP XSTKP) 
st 


30.7.2 Releasing a Stack Pointer 


You may release a stack pointer using the function RELSTK. When you do so, 
the stack frame associated with the pointer is allocated, so you may no longer 
reference it. It takes the form 


Function: RELSTK 
RELSTKP 
# Arguments: 1 
Argument: 1) a stack pointer, POSITION 
Value: POSITION, but the stack frame is released. 


If POS is not a stack pointer, RELSTK does nothing. 

You may test if a stack pointer has been released using RELSTKP. It takes 
the same argument as RELSTK and returns POSITION if the stack frame cor- 
responding to POSITION has been released. 


30.7.3 Clearing an Active Stack 
CLEARSTK releases all active stack pointers. It takes the form 


Function: CLEARSTK 

# Arguments: 1 

Argument: 1) a mode flag, FLAG 

Value: A list of active stack pointers or NIL. 


If FLAG is NIL, CLEARSTK releases all active stack pointers and returns 
NIL. 
If FLAG is T, CLEARSTK returns a list of all the active stack pointers, but 
does not release them, e.g., 


«(CLEARSTK T) 
([STACKP]#152645/COND [STACKP]#152632/FACTORIAL) 


CLEARSTK uses two lists, CLEARSTKLST and NOCLEARSTKLST, to 
determine what action to take for each stack pointer. CLEARSTKLST is a 
global variable used by EVALQT. Whenever EVALQT is called, it checks 
CLEARSTKLST, which may take three values: 
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1. If its value is T, all active stack pointers are released using CLEARSTK. 
2. If its value is NIL, nothing is released. 


3. If its value is a list, only the valid stack pointers on that list are released. 


EVALOT is entered when INTERLISP is started up, following errors, or 
when the user has performed a CTRL-D or (RESET). 

NOCLEARSTKLST is a global variable used by EVALQT to mediate the 
behavior caused by CLEARSTKLST. It is initially NIL. However, you may as- 
sign as its value a list of one or more valid stack pointers which will not be re- 
leased when CLEARSTK is called because CLEARSTKLST has the value T. 
Generally, you will want to save a few stack pointers from being released, so it is 
easier to set the value of NOCLEARSTKLST than it is for CLEARSTKLST. 


30.7.4 Copying Stack Frames 


The stack represents an environment for the execution of a set of functions. You 
may save that environment by copying the appropriate stack frames using CO- 
PYSTK, which takes the form 


Function: COPYSTK 
# Arguments: 2 
Arguments: 1) a stack pointer, OLDPOS 
2) a stack pointer, NEWPOS 
Value: A stack pointer which is the "new'' NEWPOS. 


COPYSTK copies the specified stack frames from the frame identified by 
OLDPOS to the frame identified by NEWPOS. Both basic frames and the frame 
extensions are copied by following the access chain from OLDPOS to NEWPOS 
inclusive. OLDPOS must be in the access chain from NEWPOS, e.g., it must 
appear before NEWPOS on the stack and its function must have been called 
prior to the function given by NEWPOS. COPYSTK copies the stack frames at 
the end of the stack and returns the stack pointer of the last frame so copied. 

This function is available only in INTERLISP-10. 


30.8 EXITING FROM A STACK FRAME 


When anerror occurs, you usually will enter the Break Package. Within a break, 
you may use the Break Package commands, which are implemented by using the 
stack functions described in this chapter, or the stack functions themselves to 
analyze the symptoms and causes of the break. The Break Package allows you to 
interactively debug your program to determine what caused the error. But, more 


importantly, it allows you correct the error (in many cases) and continue the 


computation. 
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In some cases, you will determine the cause and want to exit the break with 
some value being returned to the calling function that invoked the function that 
was broken. Two cases come immediately to mind: 


1. You are not able to repair the error because it requires extensive modifi- 
cation or new programming. Rather, to continue testing, you want to 
generate the value that the function would have returned, and continue 
with the computation. 

2. The function that was broken was a stub that has not yet been coded. 
You merely want to return a value that it might have returned and con- 
tinue testing at a higher level of your program architecture. 


The functions described in this section allow you to return from or to a speci- 
fied stack frame with a value. 


Returning from a Stack Frame 
RETFROM returns a value from a specified stack frame. It takes the form 


_ Function: RETFROM 
# Arguments: 3 


Arguments: 1) a stack frame, POSITION 
2) a value to be returned, VALUE 
3) a frame release flag, FLAG 


Value: The value of VALUE. 


RETFROM returns from the stack frame given by POSITION with VALUE 
as its value. You may return from the current stack frame with the value that it 
might have computed by executing the expression 


(RETFROM -1 <value)) 


If FLAG is not NIL and POSITION is a stack pointer, then the stack frame 
is released as if you had returned normally from the function represented by the 
stack frame. 

You cannot return from the top level. Any attempt to do so will cause an 
error: 


<(RETFROM T) 
ILLEGAL STACK ARG 
T 


Returning to a Stack Frame 
You may return to a stack frame by executing RETTO. Usually, you will want to 
perform this operation when intervening frames have compounded the error but 
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it was not detected until several more functions had been invoked. The basic idea 
is that there is a point in the stack from which the computation may continue 
without error provided the proper value is returned from lower-level functions. 
However, if you try to return a value from the broken function, it will not be 
utilized correctly because of the compound error problem. RETTO allows you to 


return to a stack frame with the proper value such that the computation may 
continue unimpeded. It takes the form 


Function: RETTO 
# Arguments: 3 


Arguments: 1) a stack frame, POSITION 
2) a value to be returned, VALUE 
3) a frame release flag, FLAG 


Value: The value of VALUE. 


Returning from a Stack Frame with Evaluation 

RETFROM returns the value given as its second argument. In many cases, you 
do not know what the value should be, but you do know how it can be computed. 
RETEVAL allows you to compute a value to be returned from a stack frame. It 
takes the form 


Function: RETEVAL 
# Arguments: 3 
Arguments: 1) a stack frame, POSITION 


2) an expression, EXPRESSION 
3) a frame release flag, FLAG 


Value: The value of EXPRESSION. 


EXPRESSION is evaluated in the access environment specified by POSI- 
TION. RETEVAL returns from the stack frame specified by POSITION with 
the corresponding value of EXPRESSION. In most cases, POSITION will be 
different from the stack frame in which the computation was broken because the 
correct value to be returned may be computed at a higher level in the stack. 

EXPRESSION may be any general S-expression. If the value to be returned 
is the result of evaluating a function with a known set of arguments, then you 
may use an alternative function, RETAPPLY. It takes the form 


Function: RETAPPLY 


# Arguments: 4 


Arguments: -1) a stack frame, POSITION 
2) a function, FN 
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3) a list of arguments, ARGS 
4) a frame release flag, FLAG 


Value: The result of applying FN to ARGS. 


RETAPPLY operates in a manner similar to RETEVAL. 


30.9 OPERATING ON THE STACK 


INTERLISP provides several functions for operating on the entire stack. Usu- 
ally, you will want to search the stack for a specific frame or display the stack 
structure in different formats. These functions are described in the following 
sections. 


30.9.1 Mapping Down the Stack 


You may apply a function to every frame on the stack using MAPDL because the 
stack is treated as a single large list. MAPDL takes the form 


Function: MAPDL 
# Arguments: 2 


Arguments: 1) a mapping function, MAPDLFN 
2) an initial stack descriptor, MAPDLPOS 


Value: NIL. 


Starting at MAPDLPOS, MAPDLEN is applied to each frame of the stack 
until the top of the stack is reached. MAPDLEN is a function of two arguments: 
the function name and the frame pointer itself. Consider the following example, 


<(MAPDL (FUNCTION 
(LAMBDA (X POS) 
(PRINT X)))) 
EVAL 
*PROG*LAM 
LISPX 
ERRORSET 
EVALQT 
NIL 


«(FACTORIAL 3) 
(FACTORIAL AFTER ZEROP broken) 
:(MAPDL (FUNCTION 
(LAMBDA (X POS) 
(PRIN1 POS) 
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(SPACES 3) 

(PRINT (VARIABLES POS) )))) 
[STACKP]#152567/EVAL (NIL NIL) 
[STACKP]#152567/*PROG*LAM (HELPCLOCK LISPXHIST HELPFLAG 
NIL LISPXLISTFLG LISPXLINE NIL NIL LISPXVALUE NIL NIL) 
[STACKP]#152567/LISPX (NIL LISPXID NIL NIL NIL) 


[STACKP]#152567/BREAK1 | (BRKEXP BRKWHEN BRKFN BRKCOMS 
BRKTYPE NIL) 


[STACKP]#152567/COND (NIL) 
[STACKP]#152567/FACTORIAL (xX) 


30.9.2 Searching Down the Stack 


SEARCHPDL allows you to search the stack while applying a function, 
SEARCHPDLEN, until a stack frame yields T when SEARCHPDLEN is applied 
to it. It takes the form 


Function: SEARCHPDLFN 
# Arguments: 2 


Arguments: 1) a search function, SEARCHPDLFN 
2) an initial stack position, SEARCHPDLPOS 


Value: (<name>) . (frame)); otherwise, NIL. 


SEARCHPDL operates in a manner similar to MAPDL. Starting at the 
stack frame specified by SEARCHPDLPOS, it applies SEARCHPDLEN to 
every frame. If the search function returns T, then SEARCHPDL halts and re- 
turns a value consisting of ({name) . (frame)) where (name) is the name of the 
function represented by the frame, and (frame) is the associated address. 

SEARCHPDLEN is a function of two arguments: the name of the function 
represented by the frame, and the frame itself. 


31 





The INTERLISP Compiler 


INTERLISP, like most LISP systems, is usually thought of as an interpreted 
language. However, INTERLISP provides a compiler that produces efficient 
code. This chapter discusses many of the features of the compiler but avoids 
discussion of the assembler (available only in INTERLISP-10/VAX/370) or 
other machine-dependent features. We will, however, show some samples of 
compiled code. 

The Compiler may be used to compile functions or files that contain one or 
more function definitions. Compiled code may be written into memory for later 
execution or to a file for later loading. 

Note: We do not discuss the use of Block Compiling in this text because we 
do not feel it is required on the newer versions of LISP machines that are appear- 
ing in the commercial marketplace. 


31.1 THE COMPILER DIALOGUE 


The Compiler will ask you a set of questions that help it to determine the actions 
to be taken when compiling. Your answers to these questions are used to set 
several variables which are used by the various Compiler functions and other 


system packages that it calls. 
The first question that the Compiler asks you concerns the generation of a 


listing. It appears as: 


LISTING? 


You may respond to this question in several ways. There are actually two 
sets of answers. The first set includes 


1 Print the output of Pass 1, the INTERLISP 
macrocode 
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2 Print the output of Pass 2, the machine 
language code 

YES Print the output of both passes 

NO Print no listings 


The free variable LAPFLG is set to the answer you provide. If you answer 1, 
2, or YES, the Compiler will ask you about a file name as follows: 


FILE: 


You should respond with the name of a file to which you want the output to 
be written. The free variable LSTFIL is set to the name of the file. 
Next, the Compiler will ask you about redefining your functions via 


REDEFINE? 


If you answer YES, each function will be redefined as it is compiled. That is, 
its current definition becomes the compiled code. If you answer NO, the current 
function definition remains unchanged. The free variable STRF is set to your 
response. 

Next, the Compiler asks you about saving source definitions. If you an- 
swered YES to the redefinition question, the Compiler will ask you 


SAVE EXPRS? 


If you answer YES to this question, the definitions of any functions that are 
EXPRs will be saved on their property lists under the property EXPR. Other- 
wise, the source definitions are discarded. The free variable SVFLG is set to your 
answer. 

Finally, the Compiler will ask you for the name of an output file via 


OUTPUT FILE? 


If you want to save your compiled functions for later loading, you should 
answer YES to this question. If you answer T or TTY:, the output will be typed 
at your terminal (not recommended as it may be rather lengthy). If you answer 
NO, your compiled definitions will not be saved (except in memory). 

If you answered YES, the Compiler will ask you for a file name to which the 
output should be written. If the file is already open, newly compiled code will be 
appended to the end of the file. The free variable LCFIL is set to the name of the 
file. 

I mentioned above that there was a second set of answers to the question 
concerning listings. These answers, described below, specify a complete mode of 
operation for the Compiler. 
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You may respond to the listing question with these answers as well: 


Ss Same as the last setting (which is retained by 
the Compiler) 

F Compile to a file; functions are not redefined 

ST Store new definitions for functions and save 
their current definitions under their EXPR 
properties 

STF Store new definitions, but forget their EXPR 
definitions 


31.2 COMPILATION ISSUES 


When compiling functions, there are a number of issues that you must be aware 
of that will cause functions to operate differently when compiled. These issues 
are discussed in this section. 


31.2.1 Compiling NLAMBDA Functions 


The Compiler must prepare the arguments to a function in one of three ways: 


1. Evaluated (SUBR, SUBR*, EXPR, EXPR*, CEXPR, CEXPR*) 
2. Unevaluated, spread (FSUBR, FEXPR, CFEXPR) 
3. Unevaluated, nospread (FSUBR*, FEXPR*, CFEXPR*) 


The Compiler derives its information about how to prepare a function call 
from several sources. These include (in descending order) 


1. The function definition in the file 
2. The lists NLAMA, NLAML, or LAMS 
3. The function definition in memory which is assumed to be the desired 


type 


The lists NLAMA, NLAML, and LAMS should contain the names of func- 
tions which are NUAMBDA nospread, NLAMBDA spread, and LAMBDA 
functions, respectively. These lists may be used to override the function type as 
stored in its definition if the function cannot be found in the file that is being 
compiled. ; ; 

If the function is not contained within a file or on one of the lists mentioned 
above, or is currently defined within your environment, the Compiler calls 
COMPILEUSEREN. COMPILEUSEREN has both a value and a function defi- 


nition. 
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If the value of COMPILEUSEREN is not NIL, the Compiler applies the 
value of COMPILEUSEREN to the expression that it attempted to compile and 
the CDR of the expréssion. That is, the Compiler performs 


(APPLY* COMPILEUSERFN (CDR <expression)) expression) ) 


If a non-NIL value is returned, it is compiled instead of the expression. If 
NIL is returned, the Compiler compiles the expression as a LAMBDA spread 
function which has not yet been defined. 

COMPILEUSEREN is only called when the Compiler encounters an expres- 
sion whose CAR is not a known or defined function name. 

CLISP uses COMPILEUSEREN to instruct the Compiler about how to 
compile iterative statements, IF-THEN-ELSE statements, and other constructs. 

If the Compiler cannot determine the function type by any of the means 
above, it assumes the function to be a LAMBDA spread function, and adds its 
name to the list ALAMS (for Assumed LAMbdas). ALAMS is not used by the 
Compiler, but is maintained for your benefit so that you may determine whether 
the Compiler made any incorrect assumptions or not. 


31.2.2 Declarations 


A declaration is indicated by a DECLARE: expression. Declarations are in- 
cluded in functions and in files to specify what actions should be taken when the 
function or file is compiled. A declaration takes the form 


(DECLARE: . [<filepkgcoms> or <flags)]) 
Normally, expressions included in a symbolic file are treated as follows: 


1. They are evaluated when loaded. 
2. They are copied to a compiled file when the symbolic file is compiled. 
3. They are not evaluated at compile time. 


A declaration allows you to override these actions. DECLARE: is defined as 
an NLAMBDA nospread function. It evaluates each of its arguments in turn, 
although this may be modified by the value of the arguments themselves. The 
following tags may appear in a declaration: 


EVAL@COMPILE Succeeding expressions are 
evaluated at compilation. 


EVAL@LOAD Evaluate succeeding expressions 
when the file is loaded. 


DOCOPY When compiling, copy the 
following forms into the 
compiled file. 
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EVAL@COMPILEWHEN Evaluate the succeeding 


expressions if the condition 
following is true. 


EVAL@LOADWHEN Evaluate the following 
expressions based on the value 
of the first expression 
immediately after the tag. If 
the tag is T, all expressions 
are evaluated at loading. 


FIRST For expressions that are to be 
copied to a compiled file, this 
tag specifies that the following 
expressions are to appear at the 
beginning of the file. 


DECLARE: expressions are processed in a special manner by the Compiler. 
DECLARE: is used in two ways: 


1. To specify expressions that are to be evaluated at compile time, presum- 
ably to affect the compilation (for example, using FMEMB instead of 
MEMB). 

2. To indicate which expressions appearing in the symbolic file are not to be 
copied or compiled into the output file. 


31.2.3 Open Functions 


When a function is called from a compiled function, the stack frame must be 
initialized with the argument lists and control information to ensure proper link- 
age to and return from the function. If your functions are relatively small (a few 
expressions), then the setup time may exceed the actual execution time of the 
function. When your system consists of many small functions (as encouraged by 
a structured programming effort), the housekeeping time may dominate the ac- 
tual execution time. Many small system functions are compiled open; that is, 
they do not require a function call, but are translated into in-line code. Other 
system functions are compiled open because they are frequently used. The IRM 
describes the list of functions which are always compiled open. You may force 
either your own or other system functions to compile open through appropriate 
use of MACROs. 


31.2.4 Constants 


Constants are expressions which define “constant,” i.e., immutable values. In 
most high-level languages, when constants are compiled, they refer to a single 
location in memory. To achieve this goal in INTERLISP, the function CON- 
STANTS is provided. It takes the form 
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Function: CONSTANTS 
# Arguments: 1-N 
Arguments: 1-N) a list of variables, VAR[1] ... 
VAR[n] 
Value: A list of the variables declared as 
constants. 


CONSTANTS defines VAR[1] ... VAR[n] to be compile-time constants. 
Whenever the Compiler encounters a free reference to a constant, it will compile 
the expression (CONSTANT <variable)) instead. 

The function CONSTANT allows you to define certain expressions as de- 
scriptions of a constant value. For example, you may define a scratch list of 
length 20 as follows: 


«(CONSTANT (TO 20 COLLECT NIL)) 
(NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL 
NIL NIL NIL NIL NIL NIL) 


When encountered during interpretation, the expression will be evaluated 
each time it is encountered. However, during compilation, it is evaluated exactly 
once. 


31.2.5 COMPILETYPELST 


The Compiler understands how to compile expressions and variables. You may 

instruct the Compiler in the handling of certain expressions and variables via 

macros, declarations, COMPILEUSEREFN, and COMPILETYPELST. 
COMPILETYPELST is a list of entries of the form 


(<typename) . <function)) 


It instructs the Compiler about what to do when it encounters a datatype 
other than a list or an atom. Thus, it has a close correspondence to the function 
DEFEVAL. Whenever the compiler encounters a datum whose type is neither 
list nor atom, the Compiler looks up the type name on COMPILETYPELST. If 
an entry appears on this list whose CAR is the type name, the Compiler applies 
the expression which is the CDR of the entry to the datum. The expression 
should return a non-NIL value which will be compiled instead. If it returns NIL 
or there is no entry for the given type name on COMPILETYPELST, the Com- 
piler merely compiles (QUOTE <datum)). 


31.2.6 Compiling CLISP 


The Compiler does not know about CLISP. However, it is often asked to compile 
expressions or functions that contain CLISP constructs. To compile these ex- 
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pressions, the expressions must be DWIMIFYed You may assist the Compiler in 
performing this translation in several ways: 


1. If DWIMIFYCOMPILEFLG is T, the Compiler always DWIMIFYs ex- 
pressions before compiling them. It is initially NIL. 


2. Ifa file has the property FILETYPE with the value CLISP on its property 
list, then the Compiler functions assume that DWIMIFYCOMPILEFLG 
is T for the file, even if it is NIL. 


3. If the function definition has a CLISP: declaration, including a null dec- 
laration of the form (CLISP:), the function will automatically be 
DWIMIFYed before compiling. 


COMPILEUSEREN does this automatically for all CLISP statements and 
record package statements, so if these are the only statements in the function, 
you do not have to do anything further. 


31.3 COMPILER FUNCTIONS 


The Compiler allows you to compile either functions or files containing func- 
tions. When you compile functions, you should be aware of certain actions taken 
by the Compiler: 


1. If the function has been modified by BREAKing, TRACEing, or AD- 
VISEing, it is restored to its original state before compilation. The Com- 
piler notifies you with a message of the form “<function) UNBRO- 
KEN”. 

2. If the function is not defined as an EXPR, the Compiler searches its 
property list for the property EXPR; if found, it uses its value as the defi- 
nition of the function. 

3. The Compiler prints a warning 


(<funetion) NOT COMPILEABLE) 


and proceeds to the next function in the list. 


31.3.1 Compiling Functions 
To compile a function, you invoke the function COMPILE, which takes the form 


Function: COMPILE 


# Arguments: 2 


Arguments: 1) a function list, FNS 
2) a destination flag, FLG 


Value: The value of FNS. 
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FNS is a function or a list of functions to be compiled. COMPILE asks a set 
of standard questions. It then compiles each function in FNS using its current 
definition. If FLG is T, and compiled code is to being written to a file, the file is 
closed when COMPILE terminates. If FLG is NIL, successive calls to COMPILE 
will append additional compiled code to the end of the file. Consider the follow- 
ing example: 


«(COMPILE 'FACTORIAL) 
listing? Yes 

file: F.LST 

redefine? No 

output file? No 
(FACTORIAL (X) NIL) 
(FACTORIAL) 


<(PRINTDEF (READFILE 'F.LST)) 
((FACTORIAL (X) 
NIL) 
(ENTERF 1 0 0 0) 
of 
(LDV X 0) 
(SKES 0) 
(JR 2) 
(LQI 1) 
(RET) 
2 
(PIUNBX (VREF X 0)) 
(LPUSHN 1) 
(PIUNBX (VREF X 0)) 
(SUBI 1 , 1) 
(FCLL MKN) 
(ACLL FACTORIAL 1) 
(FCLL IUNBOX) 
(IMULM 1 , 0 (CP) 
(LPOPN 1) 
(FCLL MKN) 
(RET) 
FACTORIAL 
(JSP 7 , ENTERF) 
(262144 0) 
(O PLITORG) 
wi 
(HRRZ 1, (VREF X 0)) 
(CAIE 1 , ASZ 0) 
(SRST (TREF 2)) 
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(HRRZI 1, ASZ 1) 

(POPJ CP ,) 

2 

(PIUNBX (VREF X 0)) 
(PUSH CP, = 4456449) 
(PUSH CP , 1) 

(PIUNBX (VREF X 0)) 
(SUBI 1 , 1) 

(PUSHJ CP , MKN) 

(ACCALL 1 , ' FACTORIAL) 
(PUSHJ CP , IUNBX) 
(IMULM 1 , 0 (CP)) 

(POP CP , 1) 

(SUB CP , BHC 1) 

(PUSHJ CP , MKN) 

(POPJ CP ,) 

LITORG 4456449 PLITORG (VARIABLE-VALUE-CELL X . 11) 
FACTORIAL) 


31.3.2 Compiling a Definition 
COMPILE! compiles a definition for a function. It takes the form 


Function: COMPILE1 
# Arguments: 2 


Arguments: 1) a function name, FN 
2) a definition, DEFINITION 


Value: The compiled form of the definition. 
Consider the following example: 


<(COMPILE1 'ADD3 '(LAMBDA (X Y Z) (IPLUS X Y Z))) 
(ADD3 (X Y Z) NIL) 
(ADD3 (X Y Z) NIL 
(ENTERF 3 0 0 0) 
-1  (PIUNBX (VREF X 0)) 
(LPUSHN 1) 


{rest of the definition) 


COMPILE is used by most of the other Compiler functions. It redefines FN 
with the compiled code of DEFINITION if STRF has the value T. If DEFINI- 
TION contains CLISP operators and DWIMIFYCOMPFLG is T, COMPILE1 
calls DWIMIFY before compiling DEFINITION. 
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31.3.3 Compiling Symbolic Files 


TCOMPL is used to compile symbolic files. It produces a file containing com- 
piled code that is equivalent to the S-expressions in the original file. It takes the 
form 


Function: TCOMPL 

# Arguments: 1 

Argument: 1) a list of files, FILES 

Value: A list of the output files corresponding 


to the compiled files. 


FILES is either an atom, e.g., the name of a file to be compiled, or a list of 
files to be compiled. TCOMPL asks the standard Compiler questions (see Sec- 
tion 31.1) except for the one concerning the output file. The compiled code will 
be written to a file of the same name as the source file, but whose suffix is either 
COM for INTERLISP-10 or DCOM for INTERLISP-D. 

TCOMPL will not compile any functions whose name appears on the list 
which is the value of DONTCOMPILEEFNS. This variable initially has the value 
NIL. 

If FILES is a list, TCOMPL processes the list one file at a time. It operates 
as follows: 


1. The entire file is read into memory. 
2. For each FILECREATED expression, it notes the functions that were 
marked as changed by the File Package. 


3. If the file name atom has the property FILETYPE with value CLISP ora 
list containing the value CLISP, TCOMPL sets DWIMIFYCOMPFLG 
to T so that any expressions in the file are DWIMIFYed before being 
compiled. 


4. For each DEFINEQ, TCOMPL will 


add NLAMBDA names to the list NUAMA or NLAML 
add LAMBDA names to the list LAMS 


so that calls to these functions are properly generated. 

5. Expressions beginning with the atom DECLARE: are processed as de- 
scribed in Section 31.2.2. 

6. All other expressions are collected for writing to the output file. 

7. Each function is compiled, and the compiled code is written to the output 
file. 

8. All other expressions are written to the output file. 

9. The file is closed. 
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INTERLISP/370 Convention 


Because of the limited name space available under VM/SP, INTERLISP/370 
uses a different naming convention. All files in INTERLISP/370 consist of five 
characters followed by a # followed by two digits indicating the current version. 
The file type is always LISP. INTERLISP/370 creates a file name for the com- 
piled code by appending the first four characters of the file name to the letter X. 
Thus, if. 1 compiled a file whose name is MAPFN#00, INTERLISP/370 would 
create a file named XMAPF¥#00 into which it writes the compiled code. 
Consider the following example: 


(TCOMPL 'COMPLEX) 
listing? Yes 

file? COMPLEX.LST 
redefine? No 
(COMPLEX (R I) NIL) 
(REAL (CX) NIL) 
(IMAG (CX) NIL) 
(CPLUS (CX1 CX2) NIL 


and so on for other functions in the file COMPLEX. 
(<KAISLER)COMPLEX.COM.1) 


31.3.4 Recompiling a File 


When you make changes to a file, you often want to recompile those functions. If 
your files contain many functions, recompiling the entire file may be very time- 
consuming. RECOMPILE allows you to update a compiled file without having 
to recompile every function in the file. RECOMPILE does this by compiling the 
changed functions. It then copies the definitions of unchanged functions from 
the compiled file to a new file along with the compiled definitions of changed 
functions. It takes the form 


Function: RECOMPILE 


# Arguments: 3 


Arguments: 1) a prettyfile, PFILE 
2) a compiled code file, CFILE 
3) a list of functions, FNS 


Value: The name of the new compiled file. 


PFILE is the name of a source file in PRETTYDEF format. CFILE is the 
name of a compiled code file containing definitions that may be copied. FNS 
indicates which functions in PFILE are to be recompiled. PFILE, not FNS, 
drives the action of RECOMPILE. 


1090 The INTERLISP Compiler 


RECOMPILE will ask you the standard compiler questions, except for 
“output file?”’. It uses the file map to locate the definitions of functions which 
must be recompiled. For each function in the file, RECOMPILE determines 
whether it must be compiled or not. If so, it is compiled and the code written to 
the next version of CFILE. If not, the corresponding compiled code is merely 
copied from the old version of CFILE to the new one. As it goes, RECOMPILE 
builds a file map for the new version of CFILE. 


31.4 COMPILED CODE 


In general, it is not very interesting to examine the compiled code produced by 
INTERLISP because of all the facilities available to you to examine your pro- 
grams at the source language level. However, some readers may be curious to see 
what compiled code looks like. For your edification, I duplicate some examples 
of compiled code for a few functions that have been mentioned in previous exam- 
ples. The machine language is that produced by INTERLISP-D running on a 
Xerox 1100 Scientific Information Processor. 

In the following examples, I show the INTERLISP source code followed by 
the compiled code that was printed in the listing file. 

First, a very simple function: 


(DEFINEQ 
(alldemons? (node) 
(GETPROP node 'demons) 
)) 


ALLDEMONS? (node) LAMBDA 
#{node) 'DEMONS [GETP] RETURN 


ALLDEMONS? 

name table: 

(L (0 NODE) ) 

code length: argtype: 0 
(IVAR 0) 

ACONST 0 

(ATOM . DEMONS) 

GETP 

RETURN 


Next, a slightly more complex function: 


(DEFINEQ 
(do-off-of-demon (off) 
(COND 
((EQUAL (CAR off) (CAR inheritance)) 
(MAPCAR (GETPROP node 'offspring) 
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)) (FUNCTION do-demon) ) )) 


Note that INHERITANCE and NODE are both used freely by this function. 


DO-OFF-OF-DEMON (node) LAMBDA 
{OFF) [CAR] < INHERITANCE) [CAR] [EQUAL] NFJUMP 12 
BIND[$w,$z,$v] (OFF) JUMP 7 

4: COPY [CAR] [DO-DEMON] SETQ <$w) POP #<{$z) NTJUMP 10 
#<{$w) [CONS1] SETQ <$v) JUMP 11 

10: #<{$w) [\RPLCONS] 

11: SETQ <$z)> POP 

7: [CDR] [LISTP] NTJUMP 4 
#< $v) 

12: RETURN 


DO-OFF-OF-DEMON 

name table: 

(I 0 OFF 3 INHERITANCE) 
code length: argtype: 0 
(IVAR 0) CAR 

(FVAR 3) CAR 

FN2 0 

(FN.EQUAL) 

NFJUMPX 36Q 

BIND 60Q 2 

(IVAR 0) JUMPX 23Q 

COPY CAR FN1 O (FN.DO-DEMON) 
(PVAR« T 0) 

(PVAR 1) NTJUMPX 7 

(PVAR 0) 

'NIL CONS 

(PVAR<- 2) 

(JUMP 1) 

(PVAR 0) 

RPLCONS 

(PVAR« fT 1) 

CDR LISTP NTJUMPX 355Q (PVAR 2) RETURN 


31.5 COMPILER ERROR MESSAGES 


The Compiler may emit a large number of error messages in response to unusual 
conditions it encounters while trying to compile your source files. These mes- 
sages are listed below with a statement of the possible cause. 
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(fn) NOT COMPILEABL 
An EXPR definition for FN cannot be found by the Compiler. No code is pro- 
duced for the function. The Compiler proceeds to the next function, if any. 


(fn) NOT FOUND 

RECOMPILE has attempted to copy a compiled code definition for FN from 
CFILE and has not been able to find one. No code is copied and the Compiler 
proceeds to the next function, if any. 


(* --) COMMENT USED FOR VALUE 
A comment appears in a context where its value will be used as an argument to a 
function. The compiled function will run, but the value at the point where the 
comment appeared will be “‘undefined’’. 


(<form))—NON-ATOMIC CAR OF FORM 
You intended to use the value of <form) as a function name. The Compiler as- 
sumes this and compiles the expression as if APPLY* had been used. 


(SETQ <var) (expr) --) BAD SET 
You specified a SETQ of more than two arguments in your source code. 


(fn) USED AS ARG TO NUMBER FN? 
The value of a predicate, such as GREATERP or EQ, is used as an argument to 
a function that expects numbers. 


(fn) NO LONGER INTERPRETED AS FUNCTIONAL ARGUMENT 

The Compiler has assumed that FN is the name of a function. This message 
appears when FN is not defined, but is a local variable of the function being 
compiled. That is, you intended to APPLY the value of FN, but did not do so. 


(fn) —ILLEGAL RETURN 
A RETURN is encountered in the function definition which does not occur 
within the scope of a PROG. 


(tag) ILLEGAL GO 
A GO was encountered which did not appear within the scope of a PROG. 


{tag) MULTIPLY DEFINED TAG 
A PROG label has been defined more than once within the scope of the same 
PROG. The second definition is ignored. 


<tag) -UNDEFINED TAG 
A PROG label has not been defined within the scope of a PROG expression. 
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<var)—NOT A BINDABLE VARIABLE 
VAR is either NIL, T, or not a literal atom, but one which you tried to bind 
somehow in an expression, PROG, or function definition. 


(var) <value) -- BAD PROG BINDING 
This message occurs when there is an erroneous PROG binding of the form 
(<var) <valuel) ... ¢valueN)). 

Various other messages appear during block compiling and, for IN- 
TERLISP-10/VAX/370, during the assembly phase of the compilation process. 
Consult the IRM for more information on these errors. 
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AS'\Editor command) [[9;6610) 5. os.65 bat oF eS CAG. eats pnw sere e ib hints oes bala bie as beets 685 
ABS 10x) [USSU orcis teeters acele tual pie. 5 prelate sip a bans wish RR SAS fae ZA STR a ROMA aS ERTS 376 
Access chain: pointer; [3052.3] x scocrien pen eee cate eda Seek any Mewapesas aa peneeneees 1059 
ACCESS; File attribute [10.4] oie seeicik cas paca oo sina chains tube aku anne Reaed Heewee a S11 
ACCESSFENS, Record Package declaration [27.9]........ 0c. cseee cece cent eee eeeeeees 988 
ADD» CHANGETRAN word. [23:10 (1156 sig sic sisters siyimrdigewecs isin dio psial erace Siete a aya acoa-crgrecvleiaid 872 
ADDASSOC (key value alst) [6.10.4] ........ ccc cece cece cere eee een ence eee en eeenes 189 
ADDPROP (atm property new flag) [7.4.1] .......cceccececeeeeeceeeseeeeesseresenes 203 
ADDSPELL (word splst index) [22.8.1] ....csscccaccovctecseccccsvevccsscsenccevonse 814 
ADDSPELL!I (word splst index) [22.8.1] .......cccecccceesnccescenvecsceneseessenees 817 
ADDSPELLFUG; variable [22-7] iv acies:s.waasakssinis gtineidead ands y eee ese ewes deeseaye 810 
ADDSTATS (statistic[1] ... statistic{n]) [25.9.2].........cccceccsecesecsccncesscevees 940 
ADDTOCOMS (coms file type) [17.7.1]... 66 cece eee eect reece erence eee eee teenatees 610 
ADDTOFILE (name file type) [17.7.1]. ..... 6. cece cece eect ener rete rete ee ee en re aces 609 
ADDTOFILES? () [17.3.11]... 0c. ccececceccscecteceeeeenessneenenseeseeeeeeeenenss 584 
ADDVARS, File Package command [17.2.3] .....0+02eseeee seen teen enter eee e ee eees 548 
ADDI (x1) [13.1.1] 0... ccc c eee e cece cece een e ene ee eee e eee te eens ene ene eee eaeeeenees 353 
ADD.OR.SUBTRACT.MATRICES (matrix! matrix2 flag) [11.4.4] ....-.6--0+-eeeee sees 320 
ADVICE, File Package command [17.2.10]....---+++eeeeeeeeee essen eee reser teen scene 556 
Advisin 
Modifying a function’s interface [21.1] ....-..--. eee ee cere eee eet e eee eee e een eenes 769 
Readvising a function [21.3].......++++seeereeeer estes reese eet tretreereeeeeeees bs 
Removing advice [21.2]....++e-ceseeeeecereeesereseessecessraceesseessceeecces is 
Saving advice on a file (72 0) I oe 4 
ADVISE (fns when where) [21.1].....-++seeeeceeeeeerseseereeeeeeeetaecesssereeeees 
ADVISED, File Package command AS) eee wi 


PPrrreCC reer Cera eee eee Do 


ADVISEDENS, System variable (21.1] 


1106 Index 


AD VISEDUMEP (lis Tae) 120 Ge osc eae aadsa 65-0 ewwhease Pedi das chee heaseceskeks 776 
AFTER, History Package command [28.4.8]...........eceecececesceceeeceucscucueees 1017 
AFTERSYSOUTFORMS, File Package variable [16.9.4] ...........0ccccccceceuceeuucs $31 
ALAMS, compiler variable [31.2.1] 6 isk sis cccicccctpsncase b 590 sasysseuns cedweemas oe 1081 
ALISTS, File Package command [17.2.4] ...........cccccccccccccccccceveneeceeeeecs 550 
ALLOCSTRING (n initchar oldptr) [10.1.1] ........ 2... ccc cccccccccecececeeeeeeeeees 277 
ALONE, read: macro option [14.4.5]. ....ccccsccesccscscedsbicivdwisescecsdinsecesers 423 
ALPHORDER: (8:9) [62758] |:05c 6's. scacs os dienes. 2b oa Wee 88.8990 4995.09 MOOT ANGUS CR URES 171 
ALWAYS 
CLISP iterative statement operator [23.4.2].......... 0c cece cece eee eee eee eeennees 850 
read -macro.option [14:4 Shai s s:5 ciao cag caw sinus anes ace ede esReeesees 40 vergece ers 422 
ANALYZE, Masterscope command [26.2.1] ........ 00. c cece cece cence eee eee eeeeeees 944 
AND (expression! ... expressionN) [S.1].......60.cccccscedescessocscescboccessansens 109 
ANTILOG CIS GSI sca cise tae cele o8'010.3.64 tesa made hadaky decease. eocaeivietwr se cees 381 
APPEND (expression! ... expressionN) [3.2.3, 6.1] ........ ccc cece cece eee eee ee eeenes 45 
APPLY. (fn arolst) (8:9; 32:3) 55 cccades. ccipas sedate ced Gare iad SSF ERA EAA ET D OR EE BG RS 239 
APPLY *: (iniiargl...:: atGn)[S:920 1. 5. ccs suet qitaigitd-ok Uae Reo. 4x we dabaleee bane ea eee cite 241 
ARCCOS (x radlansfiag): [13.6.2]! ds.aseg:s tcccisindie cpa. 06sa date can ae avcniag ide gusiaweee ys 378 
ARCHIVE, History Package command [28.4.9] ........0 ccc cee cece eee eee e eee eeeeeeees 1017 
ARCHIVED, File attribute (TOPS-20) [16.4] 0.2.0... cc ccc cece eect e eee ee eeeee 512 
ARCHIVEFN, History Package variable [28.5.3] ..........0cc cece eee eee cece eee eeenees 1023 
ARCHIVELST | system vatiable [28:1] oc os.cceccey seve seen sts ives vad eue's¢8 ev tenses 1000 
ARGSIN Ge radiansfiag) 113.62) 5 dessictiece daa Shades Ose Soe Oe os ask 0s:4RES 9 Meo HOD GH 378 
ARCEAN' (x tadiatistiag):[13.6:2) 5 v5 5 5c foals ota tcaed.a vis POMAAR SV RD ees bees REE ee 378 
ARGTAN2 (xy radiansflag) [13.6.2]. 66:6 isissis sad ood :005s ageless S80¢os cessed ese esaye 379 
ARG Ware ny) 187 Ai iciccsc chins wads a caec cass bes O80 8s Ce PekeRsaes Res aRHASs KAS oAdE s 235 
ARG NOT ARRAY, error message [18.5] .... 2.2... ccc cece cece cece c cece cc cenccccncees 644 
ARG NOT HARRAY, error message [18.5] ........ 2. ccc c cece cece eee e eee e eee eeeeees 647 
ARG NOT LIST, error message [18.5]... 2.2... e cece cere eee eee tere eeeeeteeeees 640 
ARG NOT LITATOM, error message [18.5]........ 2. c cece cece cece rete eee eeeeeeeeee 642 
ARGEIST (fii) [82753] oe 6.0 s.syersis's Sce-d Bad 5.5 ESSE OS LORS TA FEE OH SORE RR OR AMORA TESS WEEN 234 
ARGS, Break Package command [20.2.6] .........ceeeeee cece teeter eee eee eeeeeenes 739 
ARGTYPE (80 (83720 scsies coins dare aasica cee ase halek en pas was odpateh te pur Aesaiesmeres 229 
ARRAY (0: pv) [DUE] ois ccc sces dae sccviscdenneeccesesseess wes onde beeassdneennes 297 
File Package command [17.2.14]...........-eeeeeeees Greet eee eee e eee ee eeees 560 
ARRAY SPACE EXCEEDED, error message [18.5] .........2 00 eeeeeee eee eeeeeeeeeeee 643 
ARRAYBEG (xarray) (11.2.4) 6.2 0:cccesnscescnscsescessvessesveverddsoesecesessoss 302 
ARRAYBLOCK, Record Package declaration [27.7] ..........0eeeeeeeeeeeeeeeeeeeeees 987 
ARRAYORIG (xarray) [11.2.4] ..0.scccccsccccccccccocsccccecevosvsvecseseosscneces 302 
ARRAYP (expression) [4.4, 11.2.3]... . 2c ce cece cece ence eee e eee e eee e teen eeeeeeee 89,301 
Arrays : . 
Comparing two arrays [11.2.8]...... 2... cece cece erect eee nee e eee e ee eeeeeeeeeeees 306 
Copying arrays [11.2.7]........ccccccccccecccccccssccccscscesccsenscreesseeees 305 
Creating [11.1] 6... cccccccccccccoctvadeegsed esses sense tscssereasaescosvosesces 297 
Creating: INTERLISP-D [11.1.1] ......c cece cece eee e eee e eee ee ee eeneeceeeeeenes 299 
Definition Of [2:4] 2.0.00 cccnccccicns soa ce paasiededca sd eepe ses seesseseeescscetesis 29 
Dimensionality [2.4.1]...........ee cece cece ee eeee Bek Sh aw ae is Wek ne ee Oe eT 29 
Obtaining the array size [11.2.1] .... 2.66. cece ee ee cece eee eee e teen ee ee eneeeenees 300 
Obtaining the array type [11.2.2]..... 2.6... cece cece eee eee erent eee e eee e ee eees 300 
Obtaining a pointer to the array beginning [11.2.4] ..... 2... eee ee eee e eee cere eeees 301 
Setting an element value [11.2.5]... 2.6... c cece cece renee eee nent e eee ee ene eeeeees 302 
Sorting using arrays [11.5] ....... 0. cece cece e cece e eee e nee eee ence teen eee eeees 325 
Retrieving an element value [11.2.6] ......... see eee eee rece eee e eee eeeeeenenens . 304 
Using EQUALALL to determine equality [4.6.2] .........2eeeee eee ee eee eeeneereees 97 


Validating an array pointer [11.2.3] .........secee eee eee eee ener eee eeeeaeee eens 301 


Index 1107 


ARRAYRECORD, Record Packa e declarati Vises 
ARRAYSIZE (arrayptt) [1121] eeene 300 
ARRAYS FULL, error message [18.5] ............--............ chee on 643 
RURAL ERE (eae NII oo, «ta ois oj varyivs wa 14 ph pss fabs reco boaasbeake 300 
AS, CLISP iterative statement operator [23.4.6] .......0s0ccccccececececececcccecccee. 854 
ASKUSER (wait default message keylst typeahead 
lispxprintflag optionslst file) [14.7.1] .........cccccccccccecccuvccceuccceuucs 436 
Askuser package 
POOR Ree OR TIS IAD oa so 5 sg tik G42 Kuk Sus sa Canad Plsia did bak Fedaehecws 439 
RPy Mompeetion TRAD 96:5 saa P eas Ponies d chs Ghai on Lack es TOME RESTORES 438 
RR TOr OR SE ee End nt Re ee Ae 5 i 443 
ee Tees TRE EAE Ss 3 sca ane cosa sued cabcawed.a te ods todees cawekees 438 
Or Tae POS [EAC TGD ss 5:0:05 9 ¢.csains Ge'5 bin Guten ees nio reson da psam oa cae te aa aaw ee 439 
Pecenpiiiy onl renin 14 Fs oa cts ossocasiases cod eae ka camsaclecevamexeseas 436 
SRSCINL Seve PORT 5 Po dsicneas'sncsnae sau cny POR Rei OTR OTTER eS Ne RRS 444 
PSM Oe MIG ATL 5 oy. ces ent.hceXiueon ies o£kKaeaRhad es Mo aan Kee FES oan aeaas 184 
ASSOCRECORD, Record Package declaration [27.6]..........ccceccceuccucceecceuees 986 
ASSOCIATION TISES AG STO] cise) ia so 0.cos ys eis 04. cba Seu bas fos dla ele ee cast le ear aia Baw ds Goa den 184 
Adding-a value to\an'entry [6:10;4] sos caivcieeaco das vase odacnesd oss bas endsee tense 189 
Removing an entity [6;10:4)  eai5.0n Savas v Sivandacee AO faleeey WNa Reena eee ae wes an 187 
Replacmp's:value-in:an:enitty (651022) 3 <,égca‘aisccmtaanqas san aves eura vas Casnbalneasis 186 
Searching. association lists [6:10.1] «..........<00000 000 coecvesebeccseesvcsseeeveevens 184 
ATOM. (expression) (4.0) oc. osutegisstiravienaenwee's RO Cas ows tee See U Ea ee vie haa se eT Sees 81 
ATOM HASH TABLE FULL, error message [18.5].......... ccc cece eee ee eee eee eees 642 
ATOM TOO LONG; error message [1855]. oi605 605s sisieds saa eas ec beige Rede e Ong vedas 641 
ATOMRECORD, Record Package declaration [27.10] ......... cece eee sence eee e eee eees 989 
Atoms 
Binding while reading from a file [3.9.1] ......... cc ceeeee cence eee e eee ee eee eeneee 77 
Binding variable values [2.1.6]..........ccscccscccerccccccseseesssesesssseeseens 23 
Création of [2. 1550 sssscica seid eins Favs sWlesinnep neta pe bin pelle + VRS esreaipe Mule 9 97 22 
Creating atoms from strings [9.2.2]......... cs cece see e cence eee e ne eeeereeeeenees 259 
Generating a new symbol (atom) [9.2.1]... 0.6.0 ce cece cece erence reece eee e eee eeee 256 
Getting the top level value [3.9.2] ©... 0... . sce ee cece eee teen eee eee e eee eee eee ees 78 
Making atoms from substrings [ODS idee vaca ern da g's 96 W done Merad pK OD gad share Rdawrs 260 
Packing lists of characters into atom names ORE sy aetics Sea. pa weva ey eeayes tar6 Pye as 262 
Rules for atom names [9.1]........00 cece cece eect eee teen eee e ee eneeeeeeees 254 
Setting the top level value [3.9.2].........seeeeeee scene eee eee e eens teenneeeeenes 78 
Testing for [4.1] ........cecceeeceeeceeneseeeeeesneeeeereeancsenenceeseeeetees 82 
Testing variable bindings [4.7]......--.++eseeeeeee eee eeree eens eee e ener sees cess 103 
Unpacking atoms to lists of characters [OB Dp oss vias siace on Fe vive peee es gee Es wide 263 
Variable typing and declaration [2.1.7] ....+-+++sseeeeeeseee rete e eens eens eens 24 
ATTACH (x Ist) [6.2.4]......02sccesceccccsccsccccerseeserenrsssscsecesccaasensees 132 
ATTEMPT TO BIND NIL OR T, error message (18:5) 5 siesee coves eegeteeesaenonesas 645 
ATTEMPT TO RPLAC NIL, error message [18.5]...-. +--+ ++seseeeeee sree eee tee es eees 641 
ATTEMPT TO SET NIL OR T, error message PIG ST iia s asics veeeons evan ees kadeasreds 641 
ATTEMPT TO USE ITEM OF INCORRECT TYPE, error message TISiS): sche tose ens 645 
AVOIDING, Masterscope path specification [26.5] oo sucescessrcrecssesvasseorednneede 959 
B, Editor command [19.6.2]. ....+205 00 weseaevesetenctresorscesareressscerneaecees 686 
BAKTRACE (ipos epos skipfn flags) [20.5.4]... ces eeeceeceeneeeeneneeeeecceeeeeees 765 
BAKTRACELST, Break Package variable [20.5.4] 02. c cece cece crete teen en eneeeeees 76S 
BAD FILE NAME, error message [18.5] .pscsesssvensecesoaceessceredasenrreseresers 646 
BAD SYSOUT FILE, error message Se So. Reaictc Rice eae vane Oly oe w SNR RR DEST FE ne 
i mamand [28.4.8] ....6ecrsccecererasecscccccerseeasscens 
BEFORE, Hay) Te LETRA cca doesnt tn Jancesunt ones 530 


BEFORESYSOUTFORMS, File Package Var 


1108 Index 


BELOW, Editor command [19.6.3] 


BF, Editor command [19.6.4] AE TR Ae Mic IAE TS CANE ne 
Dp, Receivor pennants £99.65). 5 56 bx s Se cwsi vs aa ras 4 ceewnutevelesionas ves feaesastias tie 688 
BIND 
CLISP iterative statement operator [23.4.3]........ccccccssccccccccsccsscesececes 852 
Editor command [19;.6:0)) 3695.0566:5 4:0 b:590 64.6 Se dia Sore slag ce Sig e-we vee ev awd ees oe ve 688 
Masterscone relation: [26:4] 5: i:cis3ssi5:5:0 dis dieie ccneeg tele .'b0 0:09 tne oy Os Be eee men bade 957 
Binding 
Desp i (SO) vsiesieioasingis wa's Go ass usa paleckgs ors Besa TKS ERIS Os dig lense a sees bees 1055 
DN aOW FSO ET cars etita sce s 2t dco d te clear a cis bsg ah oe Gas heOG Eee Rea Hae eaten Gal bee 1055 
BR; Editor coriiniand 119;6:7] or jecs'6 sins ein eyo sale aise sidse bikie a/} Salat algaa ass wad widens abba Ce 690 
BEEP; Editor macho [19.6270 i:c.4i 10 aos apscaternaieca bee Pan's ad Sole 9 6 no's pide oie eee oleae eS OS 691 
BREINBUPF (atritiay (14.6:4) osa.5.c0 s.cunsiele seg dep ences th s4 0 ¥0000 TVs Sie ve nels bee cea 435 
BRSYSBUF ‘(etting) [14.624] 5 565.064 S00 secwade sess cane sib de canes Qaesaases Ua Kees 435 
BLOCKS, File Package command [17.2.17] .........0 ccc ccc c cece eee e eee e ees cceeeeees 561 
BO: ‘Editor command | (19;6.8) sss: o.0.5.5.scse.0-9. 5.005, dn slo ovc oe ibe Ses ONUaS Wee Mine haaveReeaiee 691 
BOUNDP: (vat) [45 71). cawiralseiceemaadbadscimeiaetisee oa tdde aces aeeaed spk bees waar 103 
BQUOTE, a‘splice macto [14.4.8] 3::.cis.ccvescseowasg laduslees ¢vetcyensesasweesueaes 426 
BREAK (expression) [20;3:1) 3:06 x9:0.4,sccncre ecu vievacs Ves US SANs 880.0 sox edae SeemmeyaeneN 749 
Break commands 
Abotting a break: [2052541 < <35:2.25 oso s nines Huass dee dep ee Fees visemes eases ehe eke 737 
Displaying arguments and bindings [20.2.6] ............e cece cece cece eee eee eeeee 738 
Displaying the entire stack [20.2.8]. .......... ccc cece cece cece cee e tees eceeeeee 744 
Evaltiation ‘in'a break: [20 22) vis 6:44 sa: vale. adeies acigced dee daacsades as asseeecnrey 736 
Forcing via CTREL-B (34.1.8) oasis scccsissasccssacacrssiccssascdesseatans snes 398 
Obtaining a backtrace! [20.2.7]. sin:6/s 0.6/0: < sje. as 6 can.s 0.0.6 a dive Hie se 090 50 5 vee ee oeeel's 741 
Releasing breaks. (20.2.1) i iii cai sisies cscs siasnadedlbiegs acd cesdscaseasnacwasea's 735 
Return'a value from ‘a break [20:2.:3] |. so. 605 05 vee dae ceeded ccns sveveeccassesent 737 
Setting the stack frame [20.2.9]... 2.0.0.0 ccccecccsccscccccsecccssessesescessces 745 
Setting values on the stack [20.2.10]......... cece cece cece cece eee n ee eeeeeeees 746 
Unbreaking a function [20.2.5] .......cccccccccccctecccvcccerersevecceesssceess 738 
Break macros [2022.01]. .occecc occ adic do wee she aes ee Sede s Fae sae eg pe diag sa caws sewe seee ss 746 
Break Package 
Activating a breakpoint [20.3.3] .........ccccecceccccccccncnecercceccecccceeees 754 
Breaking into a function [20.3.4].........00e cece cece eee e renee eee neeeeeeeeenes 756 
Defining a breakpoint [20.3.2]......... 0. cece eee eee eee e rece ence ene eeneeeeeeens 750 
Setting function breakpoints [20.3.1] ..........- cece cece eee eee e eee een eeeeeeeee 749 
Tracing a function [20.1] 2.2... 06. cece cece cece cece nent ence eee eeeeneeeenceees 731 
Unbreaking a function [20.4]......... ccc eee eee cece eee e eee e eee e eee ee ae aeneeeee 761 
When to break (20.3.5) c.i05cok sac e pcs ans aers.ep etic eee ee Nh 69s ibeewr seep eg ees 760 
BREAKCHAR, syntax class [14.4.1] 2.0.0.0... ccc cece eee eee eee eee eee eneeees we. 416 
BREAKCHECK (errorpos erxn) [20.3.5] ......... NOK ao ere TEC OSES Sieve DG SRN pRinte 9.es SO MRED 760 
BREAKDOWN (fn[1] ... fn[n]) [29.3.4]... 00... ccc ec cee ccc cece eee e rene teneeeseeees 1039 
BREAKIN (fn where when coms) [20.3.4]... 0.0... cece cece e eee eee eee e eee eneeeeeees 756 
BREAKREAD (type) [20.5.1] .... 00. ce eee c cece cece eee eeeeeneeeeeneeeneeeeees 763 
BREAKRESETFORMS, Break Paclage variable [20.2.12]........... 00 esse eee eeeee eee 748 
BREAKO (fn when coms) [20.3.2] ......... ccc cece eee reece ee eee eee n eect eeneneeeees 750 
BREAK1 (brkexp brkwhen brkfn brkcoms brktype ...) [20.3.3]... .....+- 00sec e eee ee eens 752 
BRKCOMS, Break Package variable [20.5.1] ........ 0. cece cece eee eee eee eee eneens 764 
BRKDWNRESULTS (retvalflag) [29.3.4] .. 0.0... c cece cece eee eee eee een anne eeeens 1039 
BRKDWNTYPE, system variable [29.3.4]. .......0cccee eee e eee e eee e ee eeeeeeee teenies 1039 
BRKINFOLST, Break Package variable [20.4.1] ..........eeeeeseeee ence eeeeeeeeeenes 761 
BROADSCOPE, CLISP property [23.7]. ....... 0.2 c cece eect e eee e eee eeeeeeeeeeeeeeees 866 


BROKENENS, Break Package variable [20.4.1].........0 eee e cece ee eeee eee eeeeeee .. 761 





Index 1109 

BT, Break Package command [20.2.7].............. 741 
BTV, Break Package eonmuns D027). Eakiedb: ObaeibbaiivbGas es 
TVA Bich Packageseac UT ee Nee eae areata re 
BTV*, Break Package command [20.2.7] ............ SRE NE Se Ce 744 
BTV!, Break Package command [20.2.7]......04 s+ 6s0e0se8eeeccccccccc cece ce, 744 
BUDE EMIT Ceara TNT BB 57 25 xcs sans inn Jausas59sabsdkwaato feoace cde 325 
BUILD-ARGUMENT-LIST (fn BEQUIMONT TE) FOTN ose cccanndaaeia caedea sheen acces 230 
BUILDMAPFLG, File Package variable CP7ASS |< xcs saan cage ett ees 540 
BY, CLISP iterative statement opetator 123:4:9) hc ged an be heme eestenes Se 854 
BYTESIZE, Fide ARAUbe [UB AL vi tana ste Seuss Seance dheneu te deere tous sane $11 
CALL. ‘Mastetacope selathons (26:4) ss3i6io5. 3 cease 0s) 5 by Sen bk nc ee Passa edacesveaws 955 
CALL SOMEHOW, Masterscope relation [26.4] ..........cccececececcuceccecuceeeucs 955 
CALLS ‘(in tisedatabase) [262752] os sociccah overs o's saa Daiaee guile Sac ow wad ten assehes Sages 966 
CALESCCIDE (Gad [267.20 iiss ascaccesexmoynews ce pie de euseede ees bis eheckaeseenee 966 
CAP, Editor commmintid $19: 6.9 5 5.2 occas 5. « cae -sesen Rae aA tie Re og PERRO RS 691 
AE LE BRDIORSIOOR BRET po sioca 5 ied Fea wind ce mas vie p ts ae aas easlee ans shee batenewess 35 
CAR/CDRE combinations [Se0. 10s cas se sian iyo se wiod oad hoeaeryosee Suaapeeenide tee Ga 37 
Case of characters 

Conversion to‘lowetr case [9:8] 5 6.6.5 < aise casei ss 9.48 Ses 050.8 cad Sete tees ee SbeeN ves 274 

‘Testing for: upper Case (9.8) vs isiicig ws aata aedaae web area pslemaare noe au loa owaadie hea sre 274 
CASEARRAY '(Gldatiay) [16:83] . ciei.sig wparee te dents pee'ed oey.ee4 908 849-95 FT5E90 TARETERS 525 
Case arrays) (16.8.3) siciesiss 65.5.sicstaws'eais tipiaaa-ane oa owaes bE sag pasar sled iste s OREN eRS s 524 

Setting of (16:8.3] iiss siecscs ass saa tve weet sate macnn sada wei saa saws es aeeanas 525 

Setting break/separator characters [16.8.3]......... 00sec cece eee cece eect ee eeee 526 
CGODEP: (iii)! [8.6] ) 5 os: ates ai trots nares teaiain 2 0:59 6S BTS Ge wah WR AIG NT ORR ala CRS Wiis, Sia NES ie 228 
CDIFFERENCE (6x1) ct2) [13<7.2) 5.05 25 fais Sinks iavis ee uiele tise s Mebane Ace b sess nee Te 388 
CDR (s-expression) [3.1].........ccccscsccccesccceccccecccnsceusresesetessusscecens 35 
CEXPR, function type [8.1.3] ......... sce c eee cece cere ener eee e ese neeeceeneseeeene 216 
CEXPR®*, function type [8.1.3] ..........ccc cece cece cece ee cernreceecseernreseceees 216 
CFEXPR, function type [8.1.3] ....... 0. cece cee cece eee ence eee eect ener teneeeeeaes 216 
CFEXPR*, function type [8.1.3] ......... 2 cece cece e eee e rete e nee e eee eeeeteneeneenne 216 
CHANGE, CHANGETRAN word [23.10.1]........00c cece cece cece e rene eeenneeee 874 
CHANGECALLERS (old new types files method) [17.5.10] .........00eeeesee seen eeeeee 601 
CHANGECHAR, prettyprinting control variable (USES) 5 icabaies aa Ve ateie eso eeeeen case 490 
CHANGENAME (fn from to) [19.3.3, 20.5.2]... 2.00: e cece cece e eee ee eee eee e eee eens 674 
CHANGEPROP (atm propertyl property2) [7.4.4]... -.--.-eseeeeee essen eet rece eeeees 208 
CHANGESLICE (n history) [28.6.6]... ....- 0-0. e cece cece cette eee n eee ee ence ee ee sees 1028 
Changetran Package 

CHANGETRAN Words [23.10.1] 0.2.22 seee cece cere eee e eee n eee e en en en sesetes 872 

Defining New CLISP words [23.10.2] 0... cecececececececenecseecresereeeesenees 874 
CHARACTER (cc) [9.4.2] .-.-cececscccecssscccctetececresevensecscssssaseccensess 266 
Characters 

Converting a code to PNAME equivalent (DAD) i ccc eva eos ties $4 4s5a% araeeasoeae's 266 

Converting to a number [9.4.1] ....+-0+:sessecreeeeseeeeettereterer stare secscees 265 

Extracting characters from atoms or strings [9.6] .....----eeee eres eect erect ee enone 271 

Obtaining the code of [9.4.3] .....----seeeeereceserersteenreeessseeessecseesces 267 

‘Teansiation Of (G44) i scicn.vevene ve red 2's Ayo a sass see ease NORE 964 Resinaneneye 268 
Character codes 

Obtaining the Nth character code [9.6] 2.2... .ecece cee ee eer tete cee eecen er eseeeees 271 

Packing character codes to atom names CS | Reon oe 

Selecting alternatives [9.7] +.5xss0+ ve oesade seeeeFaneseconnternetinesteresncnee’ ie 
CHARCODE (expression) LOGS sacnavadan pas wassney dyes mate snus Yede ered eter ness a 


aa ban bbe 66 Gee UES Ce Ee Ot eee OOS 


CHARDELETE, terminal table syntax class [15.5.1] 


1110 Index 
CHCON (atm flag rdtbl) [9.4.1].................0008- Ke SRE ROK S STEARNS OWED SA ULE 265 
CHCONE (atin) (954.0) c's sceiy ssiv5iea Gcacnin's obs atunle A RAUCG WS Sek HES CERA CHES SSE SORE 266 
CHECK, Masterscope command [26.2.5]. ............ cece acecccceaeeseesuseeceeenees 948 
CHECK.MATRIX (name row column) [11.4.2] ........... ccc cece cceccccccccecccececs 317 
CHOOZ (xword splst rel tail fn tieflag doubles) [22.6.1] ......... 0... cc cece cece cee eees 795 
CL, Editor command (19: 6:10) oisisniccs stow stents prs acai 24S a ails ese dered on ako % anion tes 692 
Clause Crrors (22.23) acice\s 905 siaselaie oes ores Wie hare de Sa TOSSING Sine Ea eee CO Ee ea Bewon 782 
CLDISABLE (operator) [23.822] 6: discs scoc ove acaca 05 6s s'p 0's WAS 9.400% 8400S 64a RS aw ew ERE * 870 
CLEANUP (file{ 1] >. FIND) TET SeThesccs 5.05.0: pach ik Paley baWO'D bc blk eS Ree vested obese $77 
CLEARBUF ile flag) '[14.6.2)) a 5.3x8 cee cee cear sere needs fen aoe Seabed oo ko csc 434 
CLEARSEK. (flag). (3007.3) 5 sisi chek onions seas taeeh de ew awa das seRonsesaadaradaaaaa's 1072 
CLISP 
Conaiitiotinl statenmeeits 12330 ss sd oon 6.09 5.5.0 ae 008 03509908 Revives 6 434 eo ae eens ane Oe 
Declarations [D325 kod vies. 65 8a 8 oF OED 5 SATE AO RES WERDER RARC OR OR OLRMACE SD ORDER 840 
Defining new iterative statement operators [23.4.8] ........... 0c cece eee cece cence 859 
Defining new words [23;5.2] ssc 33. dan ped nts bey 3 See VOe es Soe dhe aca Da Oe wwe Saba 861 
How CLISP operates [23 41) |< s:5.4c52.a2.ai aes .nces sea Se 599s Re Halle RSs ENS KOOEA DREN 834 
Infixopetators (29,252) 0.6.45 sistueins sialy wa WASH HSAs 9 a0 To Re oS e Hee Heaue ae leek 837 
lterative stateeients [25244 is S5 6.c.6o% 60 eS C6 Ra Bd Oh ORE OA CdD NR Sao OP 846 
LS. Binding operators [23.4.3] ise oii sii sie bestacas ease’ 805 0649 seeds waleste dee welees 851 
1.S.Modification operators [23.4.6]...... 00... cece cece cece eee e eee e ence eee eenenes 857 
ES, Selection. operators [23.4:4] 5 5 cassia dccasc seins 4.5 2a6CdS vise 6 08s o18 Ses wes OE 4rd 5/98 852 
1.S. Termination operators [23.4<5)] oii 5.6005 30035ac.ens aes ces eee thay eh anasaneeae’s 855 
LS, Fype operators (2324.21. 6 ss5i6.4 a cakes 55S TAORE OER ME Kgs Slee Sesae saeecsn eaas 847 
List. operators (23.20 5 ccacissisiectiecaccicaanas dp basen ea aware ses 8s salee a ees sa 4% 835 
Prefix opetator's [23.2.3] 6.0.5.0 naics.vae ves cies cae cecnds peeacemseesios aetna ees $ i4enes 839 
Relational operators: [23.2.2] vii saa cas do ease ods a soa Sacwseds bee sh tegsaseen gee 838 
CLISPARRAY, CLISP variable [23.9] «<< occ s:5 6c scab sans dsdcsasaaseciacesaoes ees 871 
CLISPBRACKET,CLISP property [23.7] « <3..05<6s.< sivsse5 veeenseccissczecdesescedenee 867 
CLISRDEC ‘(decist) [23:20:50 is hicd aie cc 050 F585 CSAP IASA NSS HRS ERAS whe bee REND > Hed Ts 841 
CLISPELG; CLISP variable [23.9]! oo: bcc scs oc F eGo sine caseaccee tees eniaabheneeeuneree 871 
CEISPHELPFLG, CLISP variable [22.5.9] ssicéisiisis osc ceiesis coe-osienee te dsieeinss tpecees 794 
CLISPIFTRANEFLG, CLISP variable [23.9]. 2... 2.2... cece cece c ccc e eee eee eee ee eeeeee 871 
CLAISPIFY 'fx- Ist) [QSiG) sais ac svasere ete aes ea,oas'e sais 40-9 Ko 0.40 eS S ASSOC eo ege Se KOeP SSD 862 
CLISPIFYENGLSHFLG, CLISP variable [23.6.1] ...... 0... ccc cece cece cece eee eee eeee 864 
CLISPIFYENS (fits):[23:8.1] oiscciss cairedes oicied stern dele cSeeeerseseyelessse toad eeed aes 869 
CLISPIFYPACKFLG, variable [23.6.1] .......ccccccccccccccccccccccccceeseesssceens 863 
CLISPIFYPRETTYFLG, prettyprinting control variable 
B18. 7.5; 2R6.10 Gsae cinta e «ala s'ianareloale o's ois ated dl papain Wo RD ans Bee, CoAT tee ee ere 491,865 
CLISPIFYUSEREN, variable [23.9] ....... 0. cece cece cence cece e rene eeeeeseeeeeeees 872 
CLISPINFIX, property [23.7] ...........00eeee- Sie Miceked Maes SU Se OeeD RNa ee DAMEN Ree? OOO 
CLISPRETRANELG, variable [23.9] ........ 02. cece e eee e eee e cence eee eeeeeeeennes 872 
CLISPTRAN (expression translation) [23.8.3]. ........0ecee cece cree eee eect eee eeeees 870 
CLISPTYPE, property [23.7]..........cceccceeeeceesceencenneeeseeeeeesesaseeesees 865 
CLISPWORD, property [23.7]..........ccceeeecee eee eee e renee eee eneeeeeeeeeeeeeees 867 
CLOCK, (ti) [292 2) isis vis celine vidas 0o0 ie. 6 Bv.0.96 ed dines 5505. HE MORE HA FOF ASA HST)6 OO NT 1033 
CLOSEALL (0): [16:5.2] icc ccsies weltgiswies cece nasa ren tek teta cr negeea cee tes Khia 514 
CLOSEF (file) [16.5.1] ...cccccssccascneccccccccvcccesscessessenasseesaesoccsseces 513 
CLOSERF? (file) [16.5.1] ...cccccscvcsececsscccnccstsccdncvsccsvesevecccceseonersss $13 
CLREMPARSELG, CLISPIFY variable [23.6.1] ..........eeeeeeeeeeeee 4 eases ees 863 
CLRHASH (xarray) [11.3.2]........ccccccsceccccccccceccccesesecccsececeeeseeseees 309 
CL:FLG, CLISPIFY variable [23.6.1]........ 0. cece cece cree eee e eee eee eeeeeeeeaeees 863 
CMULT (ex x2) [13.7.2]. accvoveccssccdssnescdsssccdesssaceseaasecstvosovness + 388 


CNDIR (dirname password) [29.6.3]. .......sceee eee eee eee e ene ee ee eee eeeeeeennees 1048 


Index 1111 


COLLECT, CLISP iterative statement opetatan [23.40 eect cic riiien ead cade bduisaw Glens 848 
COMMENTELG, prettyprinting control variable [15.7.5]..........0.ccececucececucuces 491 
COMS 
Dereon Commend TEP RNA oon oon he ck oa i pac dak avs dhe cai tet ounes 693 
File Package command SUT akc vakagn na dues Rolcn eevee eae hee ho wrk 554 
COMID; Baton cantaiaedt (O40 sc) sci ve eeaced cohesive ode eahncbcsenekk 693 
SAIN LE SOE iia sak sz cna halerras CrestRloe nia necaid e'wabide Bok te TOR Shane eed cats $32 
Pe REO hr idp can cs wires sie agk SE OROT b WAG TORT) bb kadauae date eee eons 534 
RESIS PO MAU PAD ENB oN crs on gk Sad dgidan uaa wis cn aide Bx ebboite cea wera $33 
Resting Seon me Whe 116: TOF soc caceseenaeinen ch cuce > hocteclie vidas uhictneseuee tax’ $34 
OMIA TEE anbeiasais ou ppedcane shu texicwb nieces acct te nel eee: 7 
COMPARE (namel name? type source! source2) PATTER ocd 5s Den os talks Pawaee wee 603 
COMPAREDEFS (name types sources) [17.5.11]........0cccccceeeececeuueecceeuuuecs 604 
OA it Ts Be | OR ne ce Se ee ee a eee 173 
CSPREP AL ey CUS TIMES LARUE sims os naasaalea bd oas<clveS tc cau wane Paka aea pad eee 1085 
CAIUS ERE LEI COMMON 35, SEMI TA 750 :OD otra pus Sos nbin cause e cAannilepactweduOleawnats 576 
SAPP RE Eh Uli OUR TeT IID PFN a Ns 6.9 4.59.5 neg aloo oer Sk OS Fd a aeae wad ga ubevien 1087 
Compiler 
Combing CLUS [SE26) sc snkks as decks cas gan kesanese taatwrasngneseasacers 1084 
Compiling 8 definition [313.2] iis swe s sevice Rives etd dia yan ad swe dnnclns dodawaabe? 1087 
Compiling Functions (31.30) 6 s.<oc0iva ere s9-04 whl oded bua ade sed sbesgaay kee mauaeaes 1085 
Compiling NLAMBDA functions [31.2.1] 2.0... cece cece e cece eee cece eeeeeees 1081 
Compiling symbolic files [31.3.3] 5.055. o%e0 sei ded Gh oaiete sia e's ab ewan dats ein bred beer ws 1088 
Constants (GLZ4) x5 i caae nin sacs anata ces aewkslege (eaeaued eee dauiemes teas eeezais’ 1083 
DICCTAE EONS PSE 2.21 sn Bora. 5.5 5, roid eS tas esse hace Pel kook ane haere SAE me pee Maw aeD 1082 
Open'Tanctions (3152.3) cies sea parsing coe ae eee sb ase ed Eb Ie AGE w Loe dy RES ees waa 1083 
Recompiling- wile [S134] os o-iores mavew.c node oP agae owes ndG eau dees tee RSPEI 1089 
COMPILETYPELST, compiler variable [31.2.5] .......... cece cece ees eeeeeeeeeeeees 1084 
COMPILEUSEREN, compiler variable [31.2.1] ........ 0.0 c cece cece eee e eee e ee eenes 1082 
COMPLEX (59) (1307: 2) oiocd as Sa sare kigd b Sore Sino, On sie seas ah ee wh edhe ne Va pele 9 V8 4S 387 
Complex numbers [2.2.3,13.7.2] ......ccccccsccscscccscccccsstevevsccvesscscsesessens 27 
CONCAT (string[1] ... string[N]) [10.3]. ....... cece eee eee cece cece eee e een eeeeeneees 280 
CONCATLIST (Ist) [10.3.1]. 2... .cccccccccccccseccnccccesesesssssscsesensesssccnes 281 
COND (expression! ... expressionN) [3.5] 0.0.6... ece eee scene ee eee eee e teen en ee ene 56 
Conditional execution [3.5].......0ecccccseccccccccccccececcseeeseeeeeeeesernasseene 56 
Default clauses [3.5.2]......c.ccccccccceccccccescevessscerescsssescnscessecuens 58 
Executing a COND expression [3.5.1]... 6.6 0seeeee reece eee eee e eee e een n ences 57 
Executing a SELECTQ expression FS. G2ET cca mina aral ase dogcs. 0 ty sib alg 9 00d Ae UD OE een Se 60 
Multiple case selection [3.6] ........seeeceeeeee reste ee eee eee eneeeeer sree sseees 60 
Selecting on constants [3.6.4]........6ecee rere eee ee eee e nee e eens sere essen nseaees 64 
Test phrase values [3.5.3] ..........2eeeee cece eee e tere ee ee ence ne ner eerereeeeeees 58 
CONS (expression Ist) [3.2.1, GA). vidvcsvcontccceceserecveneeseasecsensevdcisocabens 40 
Consing with NIL [3.2.1] ....---s+seeceeteeeeeeeeeeesceeeeeeeeteeenrsreeesecees ns: 
Counting [29.3.1].......cccssssssconcccceseeussecessessoceseseeceessssesesees ao 
CONSCOUNT (1) [29.3.1]... 2. cece cece cece rere eee e eee eeeen seen seeesaeeseneeaans <0 
CONSTANTS (var{1] ... var[n]) [31.2.4]... 00. ce eee cree erence ere e teen eee eens eees 
CONTAIN, Masterscope relation [26.4] .....--+++sseeeeeeeee etree ssseeeeeseen scenes on 
CONTROL (flag ttbl) [14.6.1]... eeeeeeeee eee eeserereeeeeeeennaeeeereeessneees abet 
Control chain pointer [30.2.3] ....+sssseesecsrscecrceeesessecesccsecccscserecscces wet 
Control characters [J4: 1.1}. s..042s0ccsinessr coast crease sav ccenbisernenersaterascedss +e 
COPY (expression) a | eee ee ee a A ss 
COPYALL (expression) oe 0) PPP Tert tO Ltr oo ee oe 
COPYARRAY (arrayptr) TDD DT ono can saves ted nneadetansadssoessenieweeses eased as 


COPYBYTES (srcfile dstfile start end) [16.8.4] 2... cece cece eee e eee teen eee een eenees 


1112 Index 


COPYDEF (old new type source options) [17.5.3] ........c.ccccccccccvccevcceceeecees 595 
COPY READTABLE (rdtbl) [14.5.4] ..... eda pvarstateré eiehie bole a)@ al avd siAcarelavad slats ob GPa Ce Re 429 
COPYSTE (oldpoé sewpos) (30.754) 36 oi58 5 bcs icssaeae a ews accdwoies do Fbcd ule os ecole os 1073 
COPYTERMTABLE ACEI) (95 S52) sos nc le sc ewe RERa ws oamedie dee anne Tie wah eSa oben Oke 472 
COS (x radiarisflag) [TSG.0] 6 ii. 65.5.cis e oq. v0c0 nie.8 gers gm sled eb oale 6’ ha: a'aih a cla eielavsla nee bie 377 
COUNT (exviceeniod) 16.8.2). 545 o.5.5:2s.0si0'hin vera sieve bos 3d ADONED DS SoD HES obs ho) dau Ro Ke 178 
CLISP iterative statement operator [23.4.2]...........cccceeeccecccccceceseeesece 850 
COUNTDOWN (expression: limit) [6:83] \ 6.5.0 :<,0:0 0 v0.0 000 ties 'obais 8otb as cs, ects e poe eseares 179 
SPLUUS ‘(xl x2) (SETA) s v.66 sca ors: ciare sa e'srd ages nes degre Bib'b)ee Giarsdwdlewid balou wle haw esos 388 
CREATE 
Masterscope relation: [26:4] ici. 5.050095 0.9.0 vias bee veg aeieee osasiew ect sanewesaa cares 957 
Record’ Packasce declaration (27.2) «0:5 &s.sias.cs hive cee aiiabus epson Lokaesgaege canes 979 
CREATIONDATE, File attribute [16.4] ...... 0... ccc ccc cece ccc cccccccseccvccscscecs $11 
CTRLV, terminal table syntax class [15.5.1] ...... 2... cc cece cee cece rene eeeeeeenenes 471 
CTRE-A) [4:02] ss ecsrea oio'a lec cigeld aap a area be Wk oe oralé's atenieeds Abalede wa hole Bled syecsacawh ark 398 
COREE FAYE sisi sai5:5-5ce. 9005. o3ro 9000 bie wale hho 8.85 4 ale wt adiaies whe GS wea oe Vee due Tees 398 
CERE-C [140617 049004 vis ocaieasaw coeds ee bas dae oes ain ecleseeadeaws anaes Ubawaesanbers 398 
CERE-D [S4 UL disnd 65:05:35 55:0.006 Uwe seve ow Ria wad oraa's RACES cae Te Ra en Tess Be OlbP es 399 
CURT eB CUAL io wiervinic orale o-cie\e Rivo SNOT ence PRS Ss MOK RRS eta aI VRE UES Oe aS 399 
CTRE- BIG Ti ests tices hee Aaa cde nino eae Ca Ra Ha Reale ba wR Nik BAS EER AOS Faiarotaaes 399 
CTREL-O: [TAA cca tastes pasa dease aan cect eacea sabes kee dey eearldaeicat pateanass’s 399 
CIRE-P I40A ides Cavan vee veawde es casig wae eeeed beds endals Deaslsloa Ae Male ba a awa De 399 
CTRL-Q [14.1.1] 6 TRE MEHR SIRES BAIR, FT HT, TMU & SAI ORS AAS TENS SILLS RN CENTRES PERG 400 
CTREGR [US B20 ocictie oes oc aioceddi0 bboy SF Ob 6 Een 4 $014 O58.) 1am Fede Ree RG ERE bie Oia ths 400 
CTREL-S [US LA sven cre :85 6.5 cabs eae a DTA READ HAR REO Rae oR are Ee weenie 68% 408 400 
CT RET CAS) a Gin osicle din arom jardin cine Bes ste Die Die sav ob ve aie wien bho eU Nea ds weeds e008 400 
CURE [IATL saat ative caeaay. oa Pee bey Coeacan's 00,5 Oe Sian siasrdd wide awiee are OS EO OOS 400 
CT RES VTA AT inc aco seress a areiew aah Siok 9.99 Ssc8 5.500305) ae. AO WIGE ES 5 BET RRV OTR ESA 401 
CT REAR (L4G) so vids adc ic asia wae aheivio 05 sr8. 9.5 Fada ba eee nee eng Tess SHi en ede dy O88 401 
CERELRAY [1451.00 cidicianiccarelg ais 398.99 PGF a eels Sab Aa RES Cee es os hide oleae eos.ee 401 
CT REZ 400) ccc sche ioe ciasaiabiainikins &e'ee o Biss Harsiducekiee Soe mae S69 See eae enes Hees eee 401 
CZERO (()' [13.7.2]. .:0055 050 0% ee TE TE ELE EER ere er eee eee 389 
BD, Editor command: [196.12] eiies coc iaivic acoware bares Sree hrs 8 dics Hes Sse Swe 55555 60-8 eS ses 694 
DATATYPE, Record Package declaration [27.8] ......... cece cece eee e eee eee eeeeeeees 988 
Datatypes 
Creating an instance [27.12.4] ........ccceeee cece e cece sete eee eeeeeeeneenaeees 995 
Defining new datatypes [27.12.1]........ 0. cece cece e eect renee nena eeneeeeeeee 994 
Fetching the contents of a field [27.12.2] ... 1... cece cece cece e eee e een en eeeeeee 995 
Identifying user datatypes [27.12.7] .......cce cece cece cece eee eeeeeeeeees ava e rig 997 
Obtaining the field descriptors [27.12.6] ......... cece cece eee e eee e ee eeeeee ... 996 
Obtaining the field specifications [27.12.5] ..... 6... cece ee ee eee eee eee e terre eeeees 996 
Replacing the contents of a field [27.12.3] .... 6... cece erence e eee eee e eee eee eens 993 
DATATYPES FULL, error message [18.5] ........0 0c cece eee eee e eee e eee e en eneeeeeees 645 
DATE () [29.1.1] ........ Pree Te TT ri teri ke Pee 1031 
DE (fn arglst exprs) [8.2.5]. ....... cece cece eee eee e eee eee e nee e ene e ene eeneaenns 222 
DECLARE, CLISP iterative statement operator [23.4.6] ........00ee cece een eeeeeeeeeeee 857 
DECLARE AS LOCALVAR, Masterscope relation [26.4].......:.eeeeeeee nese ene eeees 958 
DECLARE AS SPECVAR, Masterscope relation [26.4] .........0eeeeeeeeeeeereeeeeees 958 
DECLAREDATATYPE (typename fields) [27.12.1]...... 6. eee e eee eee eee e eee e eens 994 
DECLARE: 
CLISP iterative statement operator [23.4.6].........cee eee ence eee eee e eee n eee enees 857 
File Package command [17.2.18].........ce cece cece eee nee e enone ence eeeeeeeeenes 562 


DEFINE (Ist) [8.2.3] .......ccsccccccccccccccccccccccccccsceecseccssesacessseesees 220 


Index 1113 


BUR OUI CROMABED UPA Go oh.76 sue gue BOE ead AREY Sinks Wik Saks bas Pada hea’oucatwatate del 219 
DEFLIST (Ist property) [7.3.3] cp thorn Wereateina ound ua tiackexk ons ecaecke edna 202 
DEP MACKOG (denaitinn) (6:12:34 50:5. 6.cxcxa vwseenevagbansnnbeas bec vedte pak sueue uke 250 
TOES RUE ASUEO FD LISLE 5 5 sah nh onic paiielaw ok Gadlaan taka eenabeoawk shai eseiva 452 
DEL ASIOC (kee alty (GO. H SN, 9055 staayaiaad oes avehb 6 wavehincanyavonwds veedoerbees 187 
DELDEF (aire type Tile) NTS oo 5 Sg bo Rae eho k een Pascal canin Camanene ose 596 
DELE VE, FGior comand 109.518 soso ods 59h casa bo 60940 ab avec aaeeeyeeecee ee ar 694 
DELETECONTROL (type message ttbl) [15.6.3] .........ccccceccccceacevecsveucecues 477 
DELELE SP UG (OU MYLO TZ, x sce sas WAS Ae Raw sna eewad binds caadeurad avenue 293 
SE ees OL SGM PRC cad canes sh bs Se eee reer adeeb aves Peoektaneeiee 517 
DELFROMCOMS (coms manic type) [17.7.2 5 ooiiksc css cece vancescsecdesecencssccede 611 
DELFROMFILES (name type files) [17.7.2] ..........00ccceeeeecceeuceees  penales olseelne 611 
DEPTH: (Cxpression) [1251 is. sy dsincc reso ahaa Baise ass Vecereiangie goes We ean es Saale wi panes 349 
DESCRIBE, Masterscope command [26.2.3] ...........ccceeeeeeceeceereeeeseeeeeees 947 
DE (Gai Ate lstieR rs) (S222 Vass tina 32s ass & EG 9 epochs aoe Mea oan bav'oie'e ie tuuln papte Rw boy PERG 222 
DENFLG,variable.[8.2:4]) ¢ wicks asdiescsiese cc consis es0S Hawalae sae end ea eee ee od eon 221 
DIFFERENCE (81:52) [13-5 i 5: castcnatacsd cae Reeeae8SaswERS TE-KORSOR DESL pONw HERS TE: 375 
DIRCOMMANDS, system variable [29.6.2] 0.0.0... ccc cece cece een e eee eeeeees 1047 
DIRECTORY (files commands defaultext defaultver) [29.6.2] .......... cece eee e eens 1045 
DISMISSINIT, File Package variable [14.3.2] 0.0... 0... ccc cece eee ee eee eee e ee eeeeees 414 
DISMISSMAX, File Package variable [14.3.2] ..... 0... cc cece ccc ee eee eee eeeees 414 
DMACRDO;. propetty name: (8512)... ccc. cnvns eens yadenessGnslany oasra hes bs Cah Ree ease 246 
DMPHASH (harray[1] ... harray[N]) [11.3.4] ....... cece cece cece eee e ee eereeees 312 
DO, CLISP iterative statement operator [23.4.2] ......... cece eee eee eee e teen eeenee 847 
DOGOLLECT tent Ist)16. 2:5) cis saws fois pak FOE ERAN ees REO wee eee ease Rae 133 
DOCOPY, declaration tag [31.2.2] 0... ...ccccccccscscceecscncesesetecccsccsseseeees 1082 
DOT.PRODUCT (vector! vector2) [11.4.4]. 00... ccc ccc cece ee eee eee rete eee e ee eeee 324 
DRIBBLE (file appendflg) [29.4]........ 0. ccc e cece eee e eee eee e eee eee eeenenseeees 1042 
DRIBBLEFILE () [29.4]... csccscscccsssecsccsccovcsebercdesesbecssacesens sone 1042 
DUMMYFRAMEP (position) [30.5.1] ....... 60 c eee cece ener e erent eee e teens 1067 
DUMPDATABASE (fnslst) [26.7.11]..... 0. cece eee cece eee eee e nee e ene e eee eeeeenees 972 
DW, Editor command [19.6.13] 00.0.6... cece cece eee e eee e rete eee n ene eens 694 
DWIM (mode) [22.4] 2.2... .. cece cece cere eee etree eet e nese teeeneeereeseeeeeeeaes 790 
modes [22.1]... 0s cccscccwecscccsvensecessossecersseesseesescebeenssanse sees 779 
protocols [22.2] .......cseeecceeeeeceneeeeteeesseceneneeseersnscceeesaeaseess 781 
spelling correction default [22.2.1] ......+-+seeeee cree e tees etree tees teen ene eeees 781 
wait interval [22.2.1] .......ceceee cece cence eee ee ee teeeeeaeeneeeeencnseeeeenes 781 
DWIMCHECK#ARGSELG, variable [22.5.1]... 0... eee e cece eee ee eee e nee eee eeeees 794 
DWMCHECKPROGLABELSELG, variable [22.5.1]... . 6+ s2+eeee eee r eee e seen ee eee 794 
DWIMELG, variable [22.7] ......2.02cceeeeee cence ee eecsneneenenteeeeceeneraeeeces 809 
DWIMIFY (expression quietflg Ist) [22.5] .ccccscuncsccccereccscesenoesecereersesaess 791 
DWIMIFYCOMPELG, variable [22.5.1] .....--002eee seer cree eerste nett ee ten seen eens 794 
DWIMIFYCOMPILEFLG, compiler variable F31,2.G6].vccce cies cesnds eine ne spueede renee 1085 
DWIMIFYELG, variable [22.7.1] .....-+ssceecescsseerecereceenesssceasesecceserees 812 
DWIMIFYENS (fnslst) [22.5] ....00ceeeeeeeeeeeeeeereseneeeeseecsecaeeeresssereees 792 
DWIMLOADENSELG, variable [22.7] .....+++sererrereseereeeeteeecceeeeseeeeeees 810 
DWIMMESSGAG, variable [22.5.1] ....--s+seerecceeeeresseeeseesesssesssssnseeees 794 
DWIMUSERFORMS, variable [22.7] ...---+sseeerersetssterstsss sess sseeeceees sees 811 
DWIMWAIT, variable [22.2.1, 22.7] ....0ssceeesececsenrercterecarsecececcssseceees 781 
E 
Editor command [19.614] ss. s0censes saeseeneinnesie sins dad oe ede seeneaarerroenes 695 
eA linc Mul Nate a EPS A Re dns Oe 554 
File Package command [17.2.7]... ceeeecccseeceesees pe 


EACHTIME, CLISP iterative statement operator [23.4.6] ...--+.e+eeeee essere seeee eres 


1114 Index 


ECHOCHAR (charcode mode ttbl) [15.6.2]......... ccc cccccccccccccccccucucccacacuus 476 
ECHOCONTROL (char mode ttbl) [15.6.2) avis cicccndinccadasescb onder Hesesoentadeves 476 
ECHOMODE (echoflag ttbl) [15.6.1] ....... 0... cc cece ee cece eee eeeeeeenseueeceges 475 
EDIT, Masterscope command [26.2.4]..........ccc cen ccccccccccccccccceeesuceeeeece 947 
EDIT WHERE, Masterscope command [26.2.4] .:.......0ccccccccecccccuccecccceeges 947 
EDITCALLERS (atoms files coms) [19.3.4]. ........0cccccecccccccccccuceceuuceenveee 674 
EDITDEF (name type source commands) [17.5.6] ...........c0ccceccecccccccceececees 597 
EDITE (expression commands atm type ifchangedfn) [19.1.4] ............ ccc eeeuee cence 670 
EDITF (fn command[1] ... command[n]) [19.1.1] 2.0.2... 0c. cece cece cceecceccceeeceee 662 
EDITFINDP (expression pattern flag) [19.3.1] ...... 0... cece cece cece ee ee eee eeeeeeenes 673 
EDITFENS (fn command[{1] ... command[n]) [19.1.1]....... 2. ccc ccece cen cceeccceeceecs 662 
EDITHISTORY, system variable [28.1]........... cece cece ence eeeceeeeenceeueuuncs 1000 
EDITL (Ist commands atm message editchanges) [19.2] ..........0 cee ee ec ceeeceeeeeees 671 
EDITLO (Ist commands atm message editchanges) [19.2] .......... 0. ccc eee eee ee eee eee 671 
Editor 
Adding to the end of an expression [19.6.35]........... 0c cece eee ee eee eeeeeeeeeeee 715 
Advancing to the next expression [19.6.37] .........cc cece cece e een eeeeeeeeeees 716 
Ascending the editchain [19.5.3] .c.ccsiccesisedecdiesevsveasescsscioscriesabeases 678 
Assigning values to arguments [19.6.31]..........0 cece eee e eee ee eee eee eeeeees 711 
Attention-changing commands [19.6.60] ........... ccc cce cece eee ee eeeeeeeeeneee 730 
Backing up in the current expression [19.6.7] ......... ccc ce cence cece eee eeeeneee 690 
Binding macro variables [19.6.6]..........ccccee cece ee eect eee ee eee eeeeeseeeeees 689 
Canitalization [19.6.9] .icten ad gs wewnssia sa spans sjaielea aes ed apiehinip ia FAA SARS AR 691 
Clispifying expressions [19.6.10] .........: cece cece renee ence eee reese eeneeeeeees 692 
Command encyclopedia [19,6] «0 6ccicc cecisicciccs eissdceadviacragsisvelecetaemes cnuene 682 
Command execution [19.6511] )5 «os siie nnasis ciacsiss reeWon ceeandvenede ota beniebas eas 693 
Concept oficurrency [19.4.1] 6 6co.6e i ccies wis caw cee died eeenasegsebecseescene nants 675 
Conditional listing. [19.6,23) 6:65 sca-s-casiz cian wae bids ofa 9 od HET RRR TORS Bee Mee ewla ee ae 703 
Deleting balanced parentheses [19.6.8].........cceeccccescceeeerecceeneseseaeens 691 
Deleting expressions [19.6.12] .......csccscccscccetcccccsccccnencesecseeseeeens 693 
Descending a level [19.5.2].......cccccccccccccccccccccccerensessecceeseseasees 678 
Dwimifying expressions [19.6.13] ........ ccc cceeee eee e cece teen ee neneeeeeseeeees 694 
Editing atoms or strings [19.6.46] ........ccccccsccecccceesccsescssassussscouces 721 
Effect of print level [19.4.2] ........ ccs cece eee e eect eee e ete e eee eeeeneeeeeeseeees 676 
Embedding [19.6.15].....ccccccccccoveseocvsncccccescececeisseeseesenccevesoes 696 
Evaluating an expression [19.6.16] 00... .. ccc eee cece etter eee eee eee e ee eeneeee 697 
Evaluating input [19.6.14] .........cccccccceccccnccesecennesceseenesesseeenees 695 
Examining an expression [19.6.17] ...... cece ee erect seer enter eeeeeeeee 698 
Executing any one command [19.6.42]........0-eeeeeee cece eee eeeneeeeeeeeeeeeee 719 
Exiting the editor [19.6.40].........cccccccccceeceeceneseeesreressereeeseeeeeee 718 
Extracting from the current expression [19.6.58] .........00ceeeeeeeeeeeeeeeees see 728 
Finding an element [19.5.6] ..........--+65- RE eee ee Mo Tee TTT TS Cor ae 681 
Finding an expression [19.6.18].........0 ccc ccee eee eee e een ee eee eeneeeeeeeeeees 699 
Finding the Nth element [19.6.39]......... 2... cece cece eee eee eee e eee eee eeees 717 
Getting a comment [19.6.21] ...... 0c c cece cece e eee eee e eens eee eeneeeeneneee 703 
Getting a definition [19.6.19]......... cece cece eee e eee e eee e eee ee ene eenenes 701 
Getting a value [19.6.20].........ccececcccccceenceceesssesneseeeesceersesesess 702 
Going to a PROG label [19.6.22] 2.0.2... cece eee ence eee e eee e rere ee eee ne eneeees 703 
Inserting after the current expression [19.6.1]. ....... 60s ceeeeee eee e teen ee eeeeees 685 
Inserting and removing left parentheses [19.6.27].........cseeeeeeree renee eeeeenes 707 
Inserting balanced parentheses [19.6.5]... 2.6... e cece eee eee eee e eee e eee eeeees 688 
Inserting before the current expression [19.6.2] .......0:seeeeeee reese eee eneeenees 686 
Inserting comments [19.6.59]... 2.6... cece eee eee e ene eee eee ee eee eeeeeeeeenaees 729 


Inserting into an expression [19.6.24]........eceeeeeee sent eee eeeee eee eeeeeeenes 704 





Index 1115 


MOTO BO orisha tan rieiend es pees A Wena hice chest ald ads waaceancudevoses 

Invoking the Editor via CTRL-U [14.1.1] 

Reraiteves execentiyhs P2G 62091 sco ivy cule wo x asines oboe Gee ewes Sede wee babar voculs 

Joining conditional expressions [19.6.25] 

EGCene es Petters EG GiSEs ou ye cc anes tne ca oe NOEs Sa aes ewan bene aw eWawecak 

Locating an S-expression [19.6.26] 

Lower case conversion [19.6.28] 

PeaCies MSI ETDS IOS 86. ors. tay ict kp od ON aK As Aw ws eka Cain bn UES 

Making a fanction [19,6,32) < ica ie id cans saleah vem sa enc tke cd te eee ees 

Marking and restoring the editchain [19.6.33] 

Motiryrngy tke Vet striictate 119-54) soso vn ica ce ewis nosaserwancdankow es even ac 

DAONINE CXTMOREIONS 100.04) cnc sen 5 930 dae geese eR us SERN Re FETA oh OER 

Moving up the cditchain [19,6.57]..0355 csi dsascnrcaedaesaesdweenestueanesiesaeas 

Negating the current expression [19.6.36] ............cceeeececeeeeeeeeeeeeeees 

NIL comitjand | [19.6.38] oi56 inccceeis tae aed edd aad <8 Ot ees Cea aa we ROR kad bkaee aw 

Pattern specifications for searching [19.4.4]........... 0. cece cece eee cece eee e eee 

Printing the current expression [19.6.43] ......... 0. cee e cece eee eee eee e ee eeees 

Raising the case in an expression [19.6.45] ............ ccc cece eee eee cece eeeeee 

Recursive editing [19.6:95) « o:66.:3 sis saaedasdak oo ale wea vee oe wine calbn'y ese Ae wees 

Replacing an element [19.6.44] 2.0.0.0... ccc cc cece eee eee ee eee eee ee eeeee 

Right parenthesis in'[19:6;47] ci seesvnas posse snes cae vas OR SERS ROW KS aT ED TAS 

Right parenthesis out [19,648] | oc cis-2 ss coi ais so 06 '5e ed 2 ae bey Spies 4e Phi eM eee ae 'eaes 

Searching backwards [19.6.4] d:iiie'sc sie csivdis dca wee Heer ele sad Vie'erinc Ae wed SUR 

Setting a literal atom’s value [19.6.49] ........... 0. cece cece eee c cece eee eeeeneees 

Setting a tentative edit marker [19.6.53] ......... 0... cece cece eee c eee ee ee eee ees 

Showing instances [19:6.50) si.66 ni cece ecicasdiveivdessacsneriagas decode sanaadas 

Splitting conditional expressions [19.6.51].... 22.2... ccc cece cece eee eee eee e ee eeee 

Switching elements in an expression [19.6.52]........... 020 eeeeee cece cece eeeeees 

THRU and TO: Location specification [19.6.54] .......... 6c cece eee e eee eee eens 

Undoing an editor command [19.6.56]....... 6... cece ee eee eee eee eee ene eeeees 

Using the original definition [19.6.41] .......... 00 0c cece cece cette eee eee eeeeeee 
EDITP (atm command[1] ... command[n]) [19.1.3].......... 0.0 cece eee ee eee eee eens 
EDITREC (recordname com[1] ... com[n]) [27.11.1].........0 0. cece eee e eee ere eeee 
EDITRACEFN (command) [19:3:5S] «.6.6<..-c0c-e ese vie ga polky Keg shed ale ade.s Wa ase Helena 
EDITRDTBL, Editor variable: [34.4] csc ievscce ss tess edie siawespeesnesswsas sence ages 
EDITV (name command[1] ... command[n]) [19.1.2] .......... 00. eee eee eee eee ees 
EDIT4E (pattern expression) [19.3.1]....... 6... eee e cece cece e eee eee eee eee tee eeeeees 
ELT (array index) [11.2.6] ..........cceeceeeeeecce cece eset ecneseescessscesreceees 
ELTD (array index) [11.2.6]......... 0c ccc cece cece ees e eres ee ee ence nnseceeeeseennes 
ELTM (name row column) [11.4.2]........cccc cece cece cece eee ete reese eens eeneeeeees 
EMBED, Editor command [19.6.15] ........ 2. cece eee ee ee eee eee e et eeees 
ENDCOLLECT (item Ist) [6.2.5]...... cece cece cee c cece eee ee eee eect eneeeseeeeenes 
ENDFILE (file) [15.1.7] 2.0... ccc cece ccc e eee eee eee e eect een eee ennneeeeneteeeaes 
END OF FILE, error message [18.5] ........-- ee eee cece e cree eee eee ee eee ee een eeees 
ENTRY¢# (history event) [28.6.4] .......-0 ese c cece eee tenet eect eet e eee ene nee ee eees 
ENVAPPLY (fn args aposition cposition aflag cflag) 

[30.6.1] 0... ccecccccccccccnssesndeeseeeseccececeeseetenepecsscnsneasseneeee 
ENVEVAL (expression aposition cposition aflag cflag) 

(90.6.1) .. ccscvvcences ees iedaeade dvaeeresiertesiteresendasnsaas seed doaeseresios 
EOFP (file) [16.8.5]... ...ccccccscccccccceseenenensecsserecsseeseseseeeerenenenees 
EOL, terminal table syntax class [15.5.1]........ceeee sree cece cree e reteset eee e eee ee es 
EO Gx y) (4G ccc cscs cg ncceyaewes en dan deanery grins eats nae nen bt ea tees wermenas 
EQARRAYP (arrayl array2) [11.2.8] ......---eee sree eee eee e eter te eee tee secre esses 
EQLENGTH (expression length) [4.6.4]....---++++++seeeesecreee ress eeeeeesssseecees 


Ce ee we w ees sees esereeeneeseeeseesessseees 


ay 


ed 


er 


a ear 


1116 Index 


BOMEMB ‘(expression Ist) [4.8] 5 05 iiss x vias tain ans dos des dee tasndawasawe ses ns sneseneea 105 
EQSIGNE (5:9) [52010 xisceicigescod dre’ ares nedataia- ya Rie e-blecesarpag ars eiaiaglln deaied a abate dene 113 
BUSCAR a TG BPS IS cain va Lehane EAS Daa GLa oN een cle tee eedake aoe 94 
Equality 
Miiacshithe vie COMIN 14 BI «x5 x05 4a SS he chika A ROA RAN OR ek hha 107 
Atoms [4.6.2] 's ovsinsvoaqusrsainy rice eb ed e0hs huh nde aed Ove aed ae eh Deeb ane ee Rens 97 
Complex structinres (4.6.5) 5.5.0 65:5 560-06. 005 ee o's, ste ciop ey aaaie sitielens atalare dinaes Sables’ 101 
Lenathy (4:64) creas sea aia sistas cc tia Zeca sips ac ee abe cd a Bearers era's ach 69S KW RA NEES OR 100 
Non-equality![4:6: 6] 66 <5.c.00.0.04. 68405 AFA EE VESTER ULE G9 00 Eee Uae. eeeaee PRaee 102 
PUG BGS 7s da ca xcscs etoa OMe ae SMe TS Ne boo bP RENN eae RMSE RMN e Tes ROME eh oh 103 
Nun bers: §4 6:3) aise sds casas wis wR BTA RTA Oa ROU POR ERTS W Gch a Eh pall bale o bird days ale 99 
Objects: [4;:6:1) 555 caseata dd sedadels fake one cans Rees RS raodebs hoa uec Dae Wabi av o-baa hes lie 94 
TAT AE Un WV URN Gs oes 5 5a 5S TACT RA SOT Te RED OTe RI eee ea 97 
EQUALN (expression! expression2 depth) [4.6.5] .......ccccceee seen eee eeeeneeeeeeees 101 
EQP (expression! expression2) [4.6.3] .........seceeeeeeeeee eee eee eeeeeeeeeeeeeeees 99 
EQZERO (expression) [4:2:3)) caisivin.6:cainidinn cand es a 06 vigse 5d o'n'ng 04 00'8'd és or wcodigieis wale 86 
ERASE, Masterscope command [26.2.2] .......0eceeeeeeeee eee tte e eee eeeneeeeeanens 946 
ERROR (messagel message2 nobreakflag) [18.6.1] ......... 0s cece cece eee e eee ene neeeee 648 
ERRORMESS (errorform) [18.6.1]. ....... 0 ccc cece eee e eee e eee cent eee eeeeeneeees 651 
ERRORMESS1 (messagel message2 message3) [18.6.1] ......... 20 sce e cece cece e eens 652 
ERRORN ()! [1826.30 aids sieeve dicks a0 is his .08. 8 Se Vasile 6 Re Tea ele ee Lay ope goles ee aa eat 654 
Errors 
Catching in a computation [18.3] ........scecevccessccccncccnscececcessescenses 635 
Catching and handling [18.2]........cccccccccccccccereveveseseeseccesesseeeees 632 
Defining new error messages [18.6.3] .......... ces eeee cece ese eee ene seeeeeesenens 654 
Entering the error routines [18.6.4]......... cece cece eee e eee seen eeeeeeennenees 655 
Forcing an error via CTRL-E [14.1.1).......cccccccccccecesecscccccscvceserenecs 399 
Obtaining information about errors [18.6.3] ........... sees cece eee e eee ennees 654 
Obtaining the error message [18.6.3] ........ 2-0 cece cece eect eee teen ener eeeees 654 
Printing a help message, [18.6.1]....... 0c cece cece eect teeter eee teen eeeeees 649 
Printing error messages [18.6.1] ........ cece cece eee e reece tent eee een neeeeeneeaee 648 
Printing a warning to the user [18.6.1] ......... eee e cece eee eee eee eee ener eeeees 650 
Resetting the system state [18.6.2]......... 0 cece cece cece eee eee n eee ee neeeeeeeees 653 
Returning from errors [18.6.2]..........ccceeeeceeeeesereceeeeneeeeenneeseerens 653 
Types of [18.5] 6... ccccscoveseveessvacsearebresagbassadercninesssesasees Paulette 640 
ERRORSET (expression flag) [18.3].........ccceeeeee cece eee eeeeewereeeeeeneeseeees 635 
ERRORSTRING (number) [18.6.3] ....... 00. cece cece eee eee eee eee ee een eeneees 654 
ERRORTYPELST, system variable [18.2.1] ........sccccccseccceesececeveeeecseseees 633 
ERRORX (errorform) [18.6.4]....... 00: c cece eee c ee ence ence nee e eee e eee eeeeeneees 654 
ERROR! '() (WS: 2] cccice's boats aad the Ca aatepineds oss bee ee Veen Sense STENTS piesbpes 653 
ERSETQ (expression) [18.3.1].........-++- ede RE SUNS AREKS GE Dep oS so CANARIO RS EN RD 637 
ESCAPE, syntax class [14.4.1]........... je deieg avega ashe oD Pune kheNed 4 Fes aa Ws Kaas 07 415 
ESCQUOTE, read macro option [14.4.5]... 0... cece eect eee eee eee ene e eee eneeeeeees 423 
ESUBST (new old expression error flag charflag) [19.3.2]. .......-.eseeeeeeeeeeeeeeeees 673 
EVAL (expression) [8.8] .........cccceee cece eee eee eee e ener ee eeeeeeeeeeeeeeeneees 237 
Break Package command [20.2.2]........ccceeee reece nee eee e rene enneeeeeeeeenes 73€ 
Editor command [19.6.16] 0.0.0.0... ccc ccc cee eee eee ee eee cece nee eee nen eeneeee 697 
EVALA (expression alst) [8.8.2] ........:ceceeeee eee eee eee n ener ee sense eee eeeeees 238 
Evaluation 
Of typein [25.2]. 0. ivsescsvecsccccvescnddeccvsdedepesneaesengebenevatesece ses 89’ 
Next expression during reading via CTRL-Y [14.1.1] .......seeeesee eee eee eeeeeees 40: 
EVAL@COMPILE, declaration tag [31.2.2]........cceeee cece eee e eee e ee eeeeeeeeeees 108: 
EVAL@COMPILEWHEN, declaration tag [31.2.2] ©... ... ccc cee cece rece reece eee eeees 108 


EVAL@LOAD, declaration tag [31.2.2] ...... cece eee eee e ene e eee eneeeennens 108 





Index 1117 


EVAL@LOADWHEN, declaration Re SDD sitio Ses asad dic Se a ees g Sie Clea lee ee ees 1082 
POV Ree ARV ED ERIE eden ct cid oae cas aaiec aes 6 attade » Récyend oelenn venrbedicase 362 
Event 
ENING Tce ads G8 ECG Sahin She hon and octincd ashe cnt upadindelbs teaticbeoudsekaas 1004 
MUNI LO) 5a ta 516 Salas DAs CRIS NG Tete EU ee nr W UAKAC RL eae dnote 999 
OCR CE TIES or cata cid hesae hand Coeds eee C nce abd ad caw oat 1003 
EVERY (expression everyfn1 everyfn2) [5.4] .........ccccecececccececececucececuceces 116 
ee eR & | OS ee Ol en oe A Se 698 
BACHAISE (OGIY 1G. S58 Li's 50k cas cA piebinw anaes eae & aglenied Sede ew ie kers are Meus bee ws 215 
Execution 
Printing execution time'via CTRIAT [14.2:2)o5 ..535 scec daccccccces uve pees ceuieans 401 
SOCIATION Hid CT RL-C TAA By oscuro yin Ue Pe oo Rear eG bad Kha ak ca au Ckwene eden 398 
Permination via CURED (N46 VA is eisinic ainae. soe wwe siewacne ba gah oe ae ETE ew RS 399 
Existential quantinicabicn [5:51 5s ccaisisa5 a e5ascis'o Oras 9 ORR Re EER Se ne Se bats pare Uwe 119 
Exiting Inibechisy (2021). ct csicson toe cheese ide Sord Rad Oa eek DaAWOE MVE Sua ola od red ead 1034 
EXPANDMACRO (expression quietflag) [8.12.2]. ........... ccc eceeeee cece eeeeeeeeees 249 
EEXPOTCMEIAE ROE 10950051) Fes is cao sag asi ara cha enw are Rss Ap jaca SAT waa OO RS LRG 1d Dake 379 
EXPR ' 
Function type [8 1] 4.00 sass wig a a enee- F901 sees CaO eles aloes Vive sod Olea Bale wae es 213 
wariable- (IO WIM) [22s7: Bees tesknccaa Manes sibs Dawes se Att aea Vor eeu seleelaae hee 812 
Expression 
Baitiig OF TIS OAL is cannthaagaae sea Gas soma naNpade Wares RUSS Cad eae chases 670 
Finding a pattern i [195323 is canetee kann neces as .cucaekien ASUS yoy cas Bp EsEs ome 672 
Sistituting info [19.321 esx desk ose Aosstee SAC Lass oa PERN S Dales Os S4O Cuoiess k 673 
EXPRP (fn) [SiG] oxeeacicnn cles amt incre pus bee ERE Sew eeR TAT eee a tae ATR e SEER Eas 228 
EXPR*, function type [8:4] soc 5:<.5 os usisces sviae code sina doesn seas cacsecieg eesseoseees ee 214 
EXPT (5:1) [136.3] 6. Scheccdesesck nee 55s Gai awa WHEL Hed 85s ae T ERE s ESET wHRONS BE 364 
EXTRACT; Editor command [19:6.58] 6..5...6:6 ce cine. gad tae oN eee awed wesw aenene ease 728 
F, Editor command [19.6.18] . iis ois occ dcecac cecesc ess ee eseededessecsbiessseaseanes 699 
FADD] ((x)) [134i ince vce re eee aie nig iyo 4 4a a: died as aaa! ays GIES FFs F POF R ES Mae CaP ETS 371 
FAULTAPPLYFLG, variable [22.7.1] .......sccsccccscctcssccnscssncvesesesonessene 811 
FAULTARGS, variable [22.7.1] ........ ccc ccc ccc e ccc e eee ee ree ec esse ceeerenseeenes 811 
FAULT EVAL, error message [18.5] ........ 0c cece cere reece eee eee e enter eet eenees 643 
FAULTEN, vatiable [22.7.1] icc cccasswcdccass coccd noe eae tence nes se anes edeeens 812 
FAULTX, CLISP variable [22.7.1] 0.0... .. 0c cece ccc e ee eee eee eee e eee ee eee ne eeeeenees 811 
FDIFFERENCE (x1 x2) [13.4.2] ....... 0c cece cece cette eee ete e nena eeneeeeennees 371 
FEQP (x1 x2) [13.4.5]. 0... cece ccc eee cece eee e eee ener e tenet eneeeeeneeeereeeees 373 
FETCH, Masterscope relation [26.4] ..........0eeeeee eee e eee reece eee eeeneeereteees 957 
FETCHFIELD (descriptor datum) [27.12.2] .... 6.60. eeeee eee eee teen eee ee ee eeenees 995 
FEXPR, function type [8.1] ....... 00. c cece eee e ener cree teen rent neneeeensetentees 214 
FEXPR¥*, function type [8.1] .......-. ee cee cece reer eee teen eee e en en ence seen eee eanes 214 
FFILEPOS (pattern file start end skip tail case) [16.8.3].....++-s0seeeseeeee eee eeeenees 524 
FGREATERP (x1 x2) [13.4.6]......ccsceceeeeeeceeesereeerereeneneneeeneererereees 374 
FILDIR (filgrp) [29.6.1] .....2-2ceeecccescscsecesscscsseeensaeesceseenseneseenes 1044 
File 
Closing [16.5]... .cscscecesccesseccesecccnccseesesrvensacecsceesnes sees tenes 513 
Declaration of primary input [16.2.2].....--+-++seeeeeee serene eee eeeeese seer ess 501 
Declaration of primary output [16.2.3]....--.++seeeeeeee errr essere sssees seers 503 
Definition OF ILA ocoveswat cvar as ctdwge sere hae Seas ea es pens ta cReeeteesxes eyes 33 
Doeketinig [16.6] sc ivinn gah haa e ons gr nds ES ROH ASE ESY wate OHO Ye AT EE Cee See 517 
Determining the fullname of [16.2.4] ..---..+++eseeserrsree tere este ese essesss ss 505 
Felli 0 URS ETN 55 ios se nino svg wives es 28 See oa Aga HRT Sore hee ae Se opie ores = 


Finding a position in [16.8.3]......--+-+seseeeecereeeseretteseeeette esses sees 


1118 Index 


File (continued) 


Clotting ah Tile palater FLGIAN a's sce vy coesee HERS 06s cn 6d tat ons Rhadded VAROR di $22 
Laney Capea VTS oa ais cars va sain anda haa as og be sca bid a pda ae Ss kaw IRC 625 
Manipulating the file pointer [16.8.1]..........sececcecccccvecccecvccecesecceces $22 
Odteiniag the file charges [L785] 35 3055 nG + oo ove 228 So's 25's bn eds hw wanaatansaces 625 
Obtaining the file date [17.8.4]. 5.0.25 oi 40 6604 09 005002 eaessasacaredivedneccaeaecds 621 
Opening (16.3.5) ic csccs ccacaswseucecsave eT ee Tre ene satan ede 507 
Vs Pad og 6 se Sp | SER wei ae oe, Pe ene Te PPC en cr ¢-R C REeE ae 501 
Random necess [16:8] | 5 << ae sadn sre als 09 ¥ 045 veg sip essa 204s vase ba RS RaW ECO bas 521 
Renaining [16.6.2 )ic. css ccicnaniecawsoe sys ces Mtcaw ewe Wigs eke WHEE SESS Seb oles 518 
Searching 's Tie [1658-4] 5 csc cigs pies Gade ey G08 TUE aOR eGR e OREN OS Taken ee d deahe $24 
potting @ file poaiter (IG B.9) ois 6 oc sudan d 9:60.55 < on 4s 00 pon cha aE EE KESTER SERED $23 
‘Testing foran end ‘of file (16.855) | osis:as ca as's aap cea os Baswae’ay esveeoseeeaeeeesues $27 
esting fot open: files :[16.3.2)) ..00.c0:2 seals ied os e's». ele bh-an'g Hie Vet Bawa Nine Hee sadeesd de 509 
Testing input/ontput: [16.2.4] | sisis-05:0 i999 oi ewwet ia oaw Weenie cing te edsw ees hwsas eas 50S 
Testing random access [16.8.2]! «6:5. \s.4:0:0 «5's'5's 0:9 5944 $b 00010 Se) 6 a 5b 891854 003 oO NSS eR eee $23 
Writing an expression to [1821.7]: 6.6 is i005: 505.508 ded Sas oes dais ad eviews ¥6 ove nels oees 457 
FILE, File Package property [17,154] 35/0 seksi ia fienesdwesdn stasniseavaseranacageneys 539 
File directories 
Connecting to another directory [29.6.3] ........... cece cece ccc c cece cece eee eenees 1048 
Manipulating the file directory [29.6.2] .........ccscc cece eee e este teen eee eeeeeee 1044 
Reading tthe current direcotry [29.6.1].........cccccceccccccccccsccccccscccesess 1044 
FILE NOT FOUND, error message [18.5] ..........cccccccscccccccccascesecscseenes 643 
FILE NOT OPEN, error message [18.5]. ........020.cccccccccsccccesccsseccccegeceees 642 
FILE SYSTEM RESOURCES EXCEEDED, error message [18.5] ..........0eceeeeeeees 643 
FILE WON'T OPEN, error message [18.5] ......... ccc ee ccc e eee c ese e eee n eee e scenes 641 
FILECHANGES (file type) [17.8.8]... 6 60.66 6.05 sie bob dos tied de cdadcesseenccesasssseeves 625 
File Package property [17.2.4] iii sivas ccsissiisac is Hevienies ces aaeesces were ses 539 
EILECOMS (file type) [0757.5] i 5.0.0 sd0i0 65332 x sine 0s tees 09 i 0.0-9 bar eaislee’s a siesisalticns els’ 614 
FILECOMSEST (file type): [97.7.3] soca ivied ccc: dslawinre sae dda ded Daeee ons Jawad agae's aaere 612 
FILECREATED ‘(expression) [17.8:3] .6.6.cc.0sc050300000.00d00-504 Reade ews aditecasleyesys 621 
FILEDATE (fite) (07. 8:4] sis irae. ciaraiscains-aiah dain ada side a ciats wrap ams PSs See Wale SBM NS SOS weg 621 
FILEDATES, File Package property [17.1.4] ........ cece cece cece cece cece cece eeeeees 539 
FILEFNSLST: (file) [17753] sos sie sisiseees Ke K0es wae FS aide Aso wias WS She VAIS SD 6.599 NGOS 613 
FILELST, File Package variable [17.1.6] .........ccccsccsccsccceccesscseccccescnecus 542 
FILEMAP, File Package property [17.1.4].........ccccccccccccccccccvcceccccccrsress 539 
File Maps: [07 .2:5) sce oes.c005 vishc 98. iden dhs.308.959,9 55657090 SEOG eTDHE REDS OSE EES 540 
File Names (16:1). 2.5). cn. o3 gee ve see Ses eee aloe vegies PR ee SEs ResaeaeRsee ce'e0ae ee FEF 499 
Accessing a field [16.7.3] 6.s.ccsiscasaaeyisg tb obs) US 5 4 5 6S5 bw ERS SHOT RESEOLS Sas a's 520 
Constiucting [16:72] secs sis oa sidney $0 5.4: e Kb ee NOI ON Ges eRe SEEN Sart mew ennds ea ae 519 
Correcting filename spelling [22.8.5]. ........ 2... cece cece eee e eee e eee eeeeeeee ne 27 
Recognizing [16:2:5] aie .aiscs sie iersioe cfs ince sc sielid a sisson 560 vse S¥'e Nolen e8 e004 90Hs 0 ae 505 
Unpacking [16.7.3] ic cdcs cadvesina cite oie cbc gy ievsinasapses sees caret see resauensie 519 
FILENAMEFIELD (filename fieldname) [16.7.3]. ..........0. cece eee cee eee eee ee eens 520 
File Package 
Adding objects to files [17.3.11]........cccccccccccccccccccececcccceseceeseecees 584 
Changing calling function names [17.5.10] ........ 6. cece ee eee ener e eee eeeees 601 
Cleaning up files [17.3.6] ..00.cccccccccccsscccnccccseseussesressestesegegeoess 577 
Commands (17.2) 5 i iiccc:8 54 pales sata csiaw awd aeaas wid cae aeiaes dee dsess CR ssa e0/e es 542 
Comparing definitions [17.5.11] 2.2.0... . cece cece cece eee eee eee eee e scene enaee 603 
Compiling files [17.3.5]... ..cccscsescssccssccccacccscssnscnsceesecccccesscesns 576 
Copying a type definition [17.5.3] 00... .. cece cece cece ee eee e eee e een e eee eeeeeees 594 
Defining new file package commands [17.6] .......... 00. ceeeeeeeee eee eeeeeeeenes 606 


Defining new types [17.4] .......ccecccececceecccececcceecrseseesesseeesencenee 586 





Index 1119 
Deleting a type definition {17.5.4 cy sc ctvviicaareadsyues cangvees ¥ sw Ses tad ene aeds 596 
Determining {le 'statusi[V 73.7: 5 5.2 stats tis oasis oo 3 ews C8 OA RNS oF eat alwe Bd Sale 578 
Detormintig Otiec! types [L7G IST 5 sana s bias ce eve ae ey tin cv oa aed pesca ee Dee ae 605 
Determining type existence [17.5.12] ........ccccccccccccccccccccccccccceceeeees 604 
Determining what has been changed [17.3.10] ........... 0 cece ceeeneeeeeeeeeeeees 584 
Editing‘a type definition: [17:5.6] 0 civaa scdscs cane te asae vo aed tac ncadia dures eave 597 
Peaturres [E70 a os coe ci k Pie acai ee owe eee ie ROR Raa Dow dE OE CRE aw ei eto 537 
Finding ‘types it files (V7 S58 las 5 :ck pavers Bale cates hers casa vs ses ww wale alarore are Weare Slaten 581 
Getting'a type definition [175.0]... 5.5 5:5 00 orke na vistee diene v48 $a eRe Tes ew teas bas 591 
CAMing Ces TUT GAY 5 ss sas bak casas ws win shane wens Ce awk ere ee Raa OE wie wanes 575 
Loading a type detinition [17.58] 5¢<.5s.¢69 tsa wissen es o09 te Fo weeoas + das acansases 599 
Making files (075352) UTS Ss iia ¥jacelod is. ciao. scoesace POs Sie gad Reon are nese 565,573 
Manipulating file package commands [17.7] ........... 0c cece cece cece eee eeeneeees 609 
Manipulating file package types [17.5]...........ccceceeeeeecececeeeeeeeeeeeenes 589 
Marking changes to files [17.1.1, 17.3.9] ........ cc cccce cece eee scene esceens 538,582 
Noticing Tiles. [17 02) wcaaly sod stsce as .3,0:0 23 RESNG- RT AT RAEN ad DelanaH bo Cae e Rad RP HORTT 538 
Putting a: type definition, (17:52) vise sins sates oo tes else 4s. 8 9G KG ORO DOME es 593 
Remaking [17.3221 siesigntseancesaisee vs bee dive F0d ha aNlbg eelew nbamde seb eaede saw eae $72 
Renaming an object (17.529) 666s Perea ek As ewes EARS Be ack aw ede PeorRreets 600 
Saving and unsaving type definitions [17.5.7] .........ccceee cee e eee creer eeneeees 598 
Showing a type definition [17.5.5]......... cece cece cence eee eee e eens eeeeaees 596 
Unmarking changes to [17:3.9]) os sie cc oaieaieis a else Sines « isa era 559 6 55 0b Beale Baa eel, 582 
Updating files: [17.1.3]! évics.c. ads. dapanadele antes’ veg d4o oo He vilelg heehee wa Gan’ 539 
FILEPKGCHANGES ‘(type ist) '[17.3/10] oi. sc ciecieiie oo eens d vulivic waa vise oie cain deiwis eee 584 
FILEPKGCOM (command property value ...) [17.6.1] 02.0.6... cece eee eee eee teen ee eees 606 
File Package Commands 
Adding commands [17.7.1] ........ccccccssecccccccecccscseeererccessssensnes 610 
Creating a COMS variable [17.7.5]... .ccssscesgetesevwsccncdsccrcssevessassas 613 
Deleting commands from [17.7.2] ..........sccccccccccvcccccceereeneeseeeeeenes 610 
Determining objects in a command [17.7.3] ....... 6. cee eee eee cere e eee eee eennes 611 
Making a new file package command [17.7.4]...........eeeeeeeeeee ener eee eeeeee 613 
Moving an item between files [17.7.7]...... 0000s cee ce eee e eect eee teen eee eeeneeene 615 
Smashing a file’s COMS [17.7.6]...........ccceecccecceetecescessssecessesoenss 614 
FILEPKGCOMS, File Package command [17.2.12]...... 0... ce eee see eee eee e eee e eens 559 
FILEPKGFLG, File Package variable [17.1.6] ......... cee see cece eee e eee e eee eee neees 541 
FILEPKGTYPE (type prop value ...) [17.4.1]... 6... cece cece ee ence ee eee eee eee eeee 586 
FILEPOS (pattern file start end skip tail case) [16.8.3] ..........seeeeee cece eee eeeeees $23 
FILERDTBL, File Package variable [14.4] ......... 0: cece eee e eee e eee eee e ete e eens 415 
File System 
INTERLISP-D and INTERLISP-10 [16.1.2] 2.0.2... cc cece cece eee eee eee eee eens 500 
VM/SP. [1G VAD viscicie aide gcl ence stale a aiera dey ered othe a dle HGCA Fa eke OE ane 4d HK aN 499 
FILES, File Package command [17.2.19]......-- cece cece ener cence reer nett ene eeenees 562 
PILES?.C) 127327) vias evr ewes cca aes ds eae e bs Vas Samco pawind gees ya pe meee EES ees 578 
FINALLY, CLISP iterative statement operator [23.4.6]. .........00 seen cece ener eee eees 856 
FINDFILE (file nospellflag dirlst) [22.8.5]. . 0.0.0.6. see cece eee eee eee renee nee e eens 828 
FIRST 
CLISP iterative statement operator [23.4.6]....... 606s eee ee eee e eee ener e eee eees 856 
read macro option [14.4.5] ......... cece cece eee eee een eee eet ee eee ne neneeee 423 
Declaration tag [31.2.2] .......ccce cece cece eter eee e eee e teen teense eeeeennees 1083 
FILERDTBL, system read table [14.4]......... ese eee cece eee tenet eee e ence ene nees 415 
FIRSTCOL, prettyprinting control variable [15.7.5]... ..-- +. +sesseeeeee erence ee ee eens 491 
FIX (x) [13.1.7] 20.0. cccececccceceececeecsceeeenseceeseerseeesereeeceeeeseessanes 358 
History Package command [28.4.3]........+eeseeeee reeset eee t eee ee eee ee ee ees 1010 


FIXP (x) [4.2.4,13.2.3] 2.2... ccccecsccccceecceereereterereceteeensssanseresserecaes 87 


1120 Index 


FIXSPELL (xword rel spist fig tail fm ... ) [22.8.3] ........ccccccccccdscccscccccccccces 823 
FIZSPELLDEFAULT, Variable (22.2.5, 2257) a ives ecaks devcycens CNSuceNeeasddeecestion 809 
BURGE eed Reiss GRTIBOME TEE ON oi 6 Coo 5s Wow ee ORAS 2ad ERODE COREA ESOS ORHORIE CECE 809 
REBDSE LEE EL) LOUD apa ds 0aa saw REST ROE HAG ALAR ATA RN EAS PER ATK OEY End an es 374 
PLOAT (2) IGS Gh otitis scniee tc a8s nba eaecesa bai Caseb seb eeadewrevasdesvesacseaaas 375 
FLOATING OVERFLOW, error message [18.5] ........ccccccccccccccvccccccvccveces 647 
FLOATING UNDERFLOW,, error message [18.5]...........0ccesecseccecceeceeecees 647 
Floating point numbers 

AGG [TSA oes 55.58 ENA ea RONG EONS COC ORE T CRN S AON eee ote ea 370 

Boolean operators [13.4.6] si aise sie: 2o9 56 ere 090 8G Sd s Hes Ohad ERS O ESTE IOC 374 

Converting tis [USA ios4 ac 35:3 saaehesvas ooo 64s Sis Orns KOR ET ERE 985 4455s Fhe 375 

Dehihition wr [ZB]. chs Sadik ce tetce ce asics ME SANG Sa ee ged & Tee ORG US Coe eR RESO 26 

Dividing [13:64] oo sicceievacwsrraekan cease she skh sO oR RS 5 CRS RERIAS ITS RAG RHETIO 372 

Maximtint OC 193-407) etic. dx onto sinie USN FEES HOR ee Me Deleldlecieng rede dba es 374 

Minimibniat [1S A407 isc c's o isawcaicina Ceci oe heh ens WAC Anis Mois RT OS cetera eee 374 

Milltiplying [13.4.3] 65.3. ch asticeinns anaes sngea dca twa sale se wa8 R049 Heehaeesdolaboa's 372 

Negatlon or [0 31422) 2 2 os tte soa 00s aS REE HRS MASS THIEN Fo be RKO va EO SRF 371 

Range Of (25222 oic6 5 sais es eed bia & a6 Wi 4 OS 0 Od Og eh dR e be FSie bis ba bed Sate Better 26 

Subtracting [13422] s%ssisie ca saucsvaye ax aes ons sera. 2 35 42d Hae 8 aie sd aT Gia eee Tape hE 371 

Testing equality [13.4.5] oc cidiess accied saea meade s en Uevedewdedewecwi ced ede es vee d 373 
FLOAT P (expression) [4.24] 5.0) vas) sisarsen ap petes S062 tetas ecdardiedas budaesas ace toa'sis 87 
FLOOR (x) [EBs FS ise: cso uscie a:b nla 904 Red TES PORE VE EOE ESA DANIO be GER TD Oy c's ee 393 
ELTEMT (format) (15:4:5) oincc0 sio5 5 oes 23.0 Sse TST aaa hanes aadre nes we cweese ers 469 
EMAX (a1 32 055:3DD TUS ACT). ows cep eee cavewes apa nas ate ar dins seewiea aaianees3ad Tse 374 
BMIN GCE X25 os RN) TDS TI iicehclasias Hak pee ea Ge Feed nae ROR ORT ERE TA PRESS Oa be Ei 374 
PMINUS (x) [ES:42)i 8a a ob on aie a dees Pe ea S5 Oa KG SSO RENAE PR ORES REN NESE eRe 371 
FNCHECK (fn noerrorflag spellflag propflag tail) 

P22 Geb Dac Se i winis, aan alors Slocess dae Bare Cag OC Oe awe Wels Cee RM ew WER eRe ONS PRETES 826 
ENS, File Package command [17.2.1].........cccccccccccsiccsscscasscsccnccssececes 543 
EN EYP Gi) (S7165) 55 eee ore C5 NSS RS ORG OAS RESO Cee ws ly ST LAUREN OSS HATRED IO 217 
FORGET; History Package command [28.4.10] .......... 2c cece cece cece cence ee eeeeees 1018 
FOR, CLISP iterative statement operator [23.4.3] .........ceeeeee cece eee e eee eeees 851 
FPEUS (Ga: 52). 5D SADT dis casa avn dca cnadsids cde oaits gia teanseaee easseneka 370 
FQUOTIENT (x):x2) [13:44] o.. octe. 5c sSiv sci cele ceases 83 5 aFs TRUS 6 Hoe Tees CRs sess 255 372 
Frame 

basic: stack frame [30:2.1) 6 o.oo boe0.xelcriele vieoicte.cale's dee Bd ce A ARS DES Daa R alte eae 1057 

description [30.253] oc sciss:cciec o's cele ojos vicleesince eg ese de ene eee use ks neveese ease 1059 

fraine extension [30.2.2] ..ccccccrdadictnasedeegb ass avesdseres nase sisaes choses 1058 
FRAMESCAN (atm position) [30.5.3] ....... cece cece cece eee e eee e eee eeeeerenes 1069 
Feateed fee [1 2.2) osc ot che re 0:00.38 20.0 CTV sharon ESC TOT hee HONG HE RRTEERS Desens os 98 90% | 
FREEVARS (fn usedatabase) [26.7.3] ......... cece cece cece eee ee eee ee eeeeeees ‘.. 967 
FREMAINDER (x1 x2) [13.4.4] ..........--5-5- eee PETERS ee ee ee 372 
FROM 

CLISP iterative statement operator [23.4.4].......... 0c cece eee eee eee e eee ee eens 853 

Masterscope path specification [26.5] ...........cccccecccccceeeecneeesercceerees 958 
FSUBR, function type [8.1] ..0.045.025ss08 6000 ceesbegs ep cdas ads cases easweecneceeees 214 
FSUBR®, function type [8.1] 2.2... .cccsccscvecciesecccccseessesevcveevccesessesees 214 
FTIMES (x1:.22. ccs SND [ISA 53). ccce 80645-00589 0S FRE CHEROKEES ERO ER MEO ed HEE aKee 372 
FULLNAME (name recogflag) [16.2.5] .........cccccceccceeceeeenereeeeeeeeeeeeeees 505 
FPUNARG [1254] occ wasn ve hie 60a 8.08.5 6.5 vido Sy v.aiw.e Seg e/a seg eae HEAT OES EET ERS OOS 344 
Functions 

Accessing the arguments of nospread functions [8.7.4] ........-00eeeeeeeseeeeeeees 235 
Applying a function to its arguments [12.5]. .... 20.20. see cece cent ener eee e ee enees 348 


Changing object names in [19.3.3] .......... cece eee e eee ene e eee eeeeeeeeenese 674 





Index 1121 


Checking function name spelling [22.8.4]........0.cceeececcenceeeeeeeeeeeeeeeees 826 
Conipiled (sD. 3 i. sctesslsis aver sasg wd Haga see oORHAs SSlRe Fa MUTE THT RSS mT 216 
Constant eva lteation [Bi 83] 5 a6 vice. exe a5 cae. daewaca PR PCR OR p ors RIES Obl ED eRe wt 238 
Constructing FUNARGs to be passed to [12.4.2] ......... ccc cece eee cee eee ee ene 346 
Copying the definition’ of [8.5] |:555.9.0:65.d% aac hud piv'ocs ti0.0 sd Sie eis ern end oe wiggle Ware 225 
Definition: o£ (8:2:2;8.2.3)| 5s oicecdiss-+ vila dc-wale sinters wakias 4s arenas wa aan snares pad OSE 219 
Determining the arguments [8.7.1] .......sccscccecccesccsvoveseteeveseesebesves 229 
Determining the number of arguments [8.7.2] ........... ccc eee e cece eect ee eeeeees 231 
Determining the type Of (8:15) is)ioe ces scesisc cesses seses ta eseceredene e 59.085. 009 217 
Eterm 8) [EF Da cs acute areveceow acu 4450 4 a visas Wein We, wnt tsa pula a koma ohana Baca re Sioa a eRe 661 
Effect: of DENELG:(8,2:4) ics eis ajais: ia sR Vaca sad 8 RK Aa Da Med ERTS whe SaaS 221 
Evaliration GF [628.05 Sib cs sacs cxte dt creek eeslet Bai gee ecetandie a altiess. 8 Saws we Son Ree hep Weed 237 
FUNARG: mechanisin: (12:4) 5. spi aleia waesv4 s Unsere Laisa deo are seats awa Slane onan 344 
Function: composition [1.1.4] '¢.0.3.6;¢ esse esree s054iee ogcerw a selee Fasig nS P eee dre wie ened 4 
Functions versus. data [Us125) sie.c:asoie ais 000d 6b dia ab ca sre disie aid ssdiera nw died Dadian gels 4 
Getting the definition of [8.3] .sis os naps voce Wess map emacaeepis sda raweas aalawina ret 223 
LAMBDA type [8/1 .1)i las iaisresaceca:aie sherdiccecd siginses ee eicyero bre Gare gait nea aS 'eN OE Raa ee Ome 214 
NGAMBDVA= type [850510 i. o,0.si0.icais'sisttigse' sere eines aug eae dam iW es eas ae en eae sRaaies 214 
Nospread (S21 aac on sied coking Seat EES OP ey lew poner grees Po RICAN Eee ok PENNS HORS 215 
Obtaining the argument list [8.7.3]. cicccsciciccsicss coe dak oases Mosse ceeesesd esiee 234 
Passing functions as arguments [12.3] 2.0.0.0... ccc cece cece e eee eee ee eeeneeees 342 
Predicates! [S26] | <anciais-s'5 carve elegy ai a-stetd sian acaba vacant ad ease dann 8 Wise aiiwlauaig Minca elgg aldeg MK aN 228 
Primitive functions: [0 UB) oars ais' dag ae os, dia Son 3550 & pha RAIA AR ORR a OREN WA Ad 3 
Setting the arguments of nospread functions [8.7.5]........0:.e cece eee eee e ee eees 236 
Setting the definition of [8.4] ........ 2... ccc cece e cere etter e tence eeenes 224 
Sg oe) Peer ee re errr Trt Terre r rere TTT rere ry Tee er ee 215 
Spreading of arguments [8.1.2] 0.0.05. .¢0scscsvescccvcsccscascvosvenseeceesetes 21S 
Syntax ‘of ‘definition [8.2.1] i.5...6 cisegced vac eeeeeqae ese ase tas was Kos we Kenda s eh ARES 218 
THES OER a.asias hoes sa scaree nse Wee a bas bG uses ree ade eae a EeEN Y4EeE REEF 213 
FUNCTION (fn environment) [12.3]. 2.0.2.0... cece eee eee ee eee ee eee eee eeeeeeees 342 
Function: definition cells [2.1.4] es.cccsaee vance ate gacnes gees ered eager seasaapans naa ds 21 
FUNNYATOMLST, CLISP variable [23.6.1] 20.0.2... ccc cee eee c cece cece cececeeceees 864 
GAINSPAGCE ()/ [29,7220 os d:c'enaie citats 05/4 3.9ia + 6S WOS AAS INO ale evr Re ees GEE Rea aaa e 1050 
GAINSPACEFORMS, system variable [29.7.2] 20... 2:0 eeeee cece seen e nent ene eeee 1051 
GOD (ay) (1G.S24) sc sii c visio in kin es.05 cin Kine haw 4 oy RENE FR ERT ATHHES DA DSHS BAGETE 369 
GDATE (dt formatbits strptr) [29.1.1]. ..... 0... cece e cece eee eee rete eee e eee eeees 1032 
GE, CLISP operator [23.2.2] .......cccecccccseuscrreseresecsesesesesansseaceeeense 838 
GENERATE (handle value) [8.11.1].......ccsecscccccscccccccesevevcssvserereeerens 244 
GENERATOR (form compvar) [8.11.1] ........0: cece cece eee eee teen nen n eee en ee eeees 244 
Generators (B.UJ i. cccseecaces ove seve e essed tere reeneee sees meat ee weds wea bee eas 243 
GENSYM (chat) [9.2.1] ...ecccccscbedi eee saa daea celine sade ieee new esse esis tie wees 256 
GEO (x1 £2) [13.5] oicie cise vices ccs soucensunes ce eed eewbedbaeseusdsady boeaedens 375 
GETATOMVAL (atm) [3.9.2] 5 .ccd cic cs ces cecceces ee soteeteccvoneenvewegegeeeencoes 78 
GETBRK (rdtbl) [14:4.2) oc. icccc cc cccvcorecv cence aed eben ad aba sdenasedesooeosene 418 
GETCOMMENT (commentptr dstfile) [16.10.2] 2.0... 6. cece cece cece eee eee eee eens 534 
GETCONTROL (ttbl) [14.6.1]. 00. .cccceurvcccoseancnedstessasdseseverscsesoeconene 432 
GETD (fn) [8.3]... eveccccs tc cdasscccccsdecssessesevenvescoscaepeessecwsen senses 223 
Editor command [19.6.19] ....... ccc cece cece e eee e eee eee een een e et eneee teens 701 
GETDEF (name type source options) [17.5.1]. ......seeeee reece eee teen eee een en enee es 591 
GETDELETECONTROL (type ttbl) [15.6.3] 0.0.0... ce ese e cece renee eect eter eee eee ees 479 
GETDESCRIPTORS (typename) [27.12.6] ...... 6. eee ee cece eee eee rete eee eee ences 996 
GETECHOMODE (ttbl) [15.6.1] 0.0.20. cece cece eee eee e eee eee e eee e eee nen neeeens 475 


GETEOFPTR (file) [16.8.1]. 0.0... 0c cece eee ener e ence reenter eeee ener eeceensnees 522 


1122 Index 


CNIFIELDSPECS (typename) 1271250 6 os bcc edieis daa sdeekeatovesacadosons bide alpen 996 
GETFILEINFO (name attribute) [16.4] 5.....sc¢6ce0r0ccvebvevecevsvevcecsescededeaaces 510 
GEEEILEPTR ile) (16.8.5) oo civacircaawink dep tacts easenopac caanweepaercepancend 522 
SO SASH (hoy matey) PUD os ais 540s cao Gee gas wea haesdericgeeacenenaawaseusen ss 309 
GEILIS (atm: propist) (7.6) aj0.5<5:04,:0% 008 vena no a5 o8 cae cle salen aes o8,veiv vaeaereceea's 211 
GENNUM, system variable [9.2.1] ......... ccc cee eececcccccecceeeeecucveceseeeens 259 
GETPROP (atin: property) [7.2] acs ce set ease sdb acn casa es odes ns des goateasaouneewess 195 
GETPROPLIST (atin) (7225.0) e's. 0:5.0005.c:ec0.0 6 0lv'4-9:5;4 019 4-4 310,041 ence’ a. ale eal piers ewe wee a0 vanes 197 
GETRAISE (tel) [15,654] os ccic.ca9 cca. ce anv dos cncac conve ace euls oven dbp alas wd sin aaatons 480 
GETREADTABLE (rdtbl) [14:522) sia acasiacscas casa sens aaawaseea dccade egoegasesen 428 
GETRELATION (item relation inverted) [26.7.7]............cccceccccccccveccceceeeus 969 
GETSEPR (dtl): [14:42] ides cdie aeenek OKs a eed edacsiees oRedags weep naan wae kad 418 
GETSYNTAX (char) [1454.2] ie 5ca Scdderecad twp wh se 4a seeb0b cos Kaew eadebiaben abe age 417 
GEETEMPGATE (8it))[26. 7.415 <6 vin. eidg aie. U4 ee dale RES igaey eS wai bie ENce ea be Ree Wee 967 
GETTERMTABLE (tt0)) [19.553] 6a asics sid dincsinsiesscis's wae dks abd can cerwspacaareavanses 472 
GETTOPV AL: Catin) 13.952) o:5-3ccisieis Hee ns 3595's Bare ABS GUE 'RS 6109.55 919.40d Fialelate 05 B amcaelnee ole 78 
GETVAL, Editor command [19.6.20]. 0.0... 0... cc cece cece eee eee eee e eee eeeeeeeeees 702 
GET*, Editor command [196.21] ssc adie ccac er dee 600s 8i0b aw ONE OERT aT awees ONa ROS 703 
CLS UO oe cic ic ee saeu te ete agi tots e NS oe Ged tira cistawlenmiea eygem aie eed Hae tes 279 
GLOBALVARS 
Mefinition [301A] ose aka 5.4.3 ae sco'5d RAs WHERE ERE GATE aR RS ea eG HOE o BE Hae ETO ae ob 1056 
File-Package'command [17.2.2] 4 io4ccceievdve devine lva dyes sd dede sane tere eaes dee 545 
CONCH SDT ODN erecss ia wiv ic bin Gx bab 8 beapSicta Walaa HRN ERAT sUOWAW Sa Gas ele MELONS FIIES E AHS 279 
KS label) [S723 sos c8 Suse sche teas eetde oan Mais Phe tae RAEN eo Nb Bask Fae Les See 69 
Break Package:commatid (20,201) os o's ais dais die cas oa ove Nd woiewale we bce sou eeaene 735 
Editor command: [196.22] o.ci.6 oes edcires ha ste one 6 ae dk me aa wETs B HEN ee aR ED ES 703 
GREATERP (51:22) [13S ois avisciaiaas Gea Ci aicia Sd ad sags asia en sae wew han dees sie a tinea tare 375 
GREETDATES, system variable [29.5] ......... 2.2 c cece e cece cece cece eee e eee eeesees 1044 
GT CLISP operator [2322.21 5.0 & 5a 005. 8 ee x hco ys oats aie AEG ORAS TS EDR ENTE OD 838 
HARRAY: (Size) [10300 on eivore ciecee oe 89.55 53.30.9010 F 159 9 FREE TOE MRE NT VERSO TEE TSS 307 
HARRAYP (xatray) [4.4;12,321) 60 ovis ciccean agisis Ho.0 Nea ee nsec Sugse a tas ews wha geae tls 89,308 
HARRAYSIZE (xarray) (1153/4) scissiv.cevssegis 046 vst dap aaa vase daad ereaae ade nceaens 309 
HASDEF (name type source spellflag) [17.5.12]....... cc eeceeee etree reece eeeeeeees 604 
Hash ‘arrays 1111.3) 's secs akc acct sce sinaeacpyeeee ras HORNS SAY Sah bne doe tame Bal Saisie 307 
Clearing a hash array [11.3.2] o...00ccccccccccvesecerccrseteediowsesveeseasecns 310 
Creating hash arrays [11.3.1]........cccscccccccsccncccsccscvrccveenssesssceses 308 
Definition‘ of [2:4.3)5. 25o0 gees Sc ced as Fecssccy eos Coes rhe MR ES bee A GON oa oe e reieee 31 
Dumping hash arrays [11.3.4] .........ccccccsccevcncccccceeeeeeseeseeeeesesees 312 
Enlarging a hash array [11.3.2]... .cccscccscccccccccnesescesssennescesossseses 311 
Mapping across a hash array [11.3.3]........cceeeeeeeeeeeeeeeeeeeeeeeeeeeeeeees 312 
Overflow handling (11.3.8) 0.6.6 cccsccacesicaceesessadaewecesessniesosebeesseses 313 
Retrieving from a hash array [11.3.2] .........cccccccccccccccnsecseecececsvccess 310 
Storing into a hash array [11.3.2] ........cccccccccececeeensccceseesscsssceeeees 310 
Testing a hash array [11.3.1] 0... ..cscccccccccsccscccccsevevceesessdesesceseons 309 
Hash ten (0453). awsceGlie salad n ceeisigs seca g eeelsibad pelea dias eu'p ap WAU es Lama meio Tele 307 
Hash link (103 soc vase scss drewe ha sieve pierne’s nese ew 808 etre Ue dale pau peeled ners heey eas 308 
HASHRECORD, Record Package declaration [27.7]........cceceeceeeeeeee erent eeeee 987 
HASH TABLE FULL, error message [18.5] ......... cece cece nee n cece et eeeeeeeeeeeees 644 
Hash waltie: (ALS) \s51.5 vias 92 o.d.n0 9 ce.0 85.85 piso Sesibcere's nwt ky h FPR SIRT bi wale ON EOS pialgeh Cai BRL 308 
HCOPYALL (expression) [6.4.2,15.1.6].......ccccecceseececceeseeeseeesesueeneseees 147 
HELP (message! message2) [18.6.1].......cccccscccccccccecsteneseeseeseceneerenens 649 
Masterscope command [26.2.7] ........sccceseecsecesecenseeeseeseteeseneeseees 949 


HELPCLOCK, Break Package variable [20.3.5] .........csssccsceccecceecnsensencenes 760 





Index 1123 


HELPDEPTH, Break Package variable [20.3.5]..........ccccceccecccccscccccsseueees 760 
HELPTIME, Break Package variable [20.3.5]............ ccc ecee eee eceeeceeeeeeeeeees 760 
History commands 

Archiving events [28.4.9) 6.65 .605.5:5:4-0% s0:08 bapiccee'sviesaleeloe bes oaaa eee bas ebasleeuiws's 1017 

Analyzing errors (28.4.14] oii is saccade sc ages. cet ered sane ensedg Sbeasceesawveds 1019 

Bypassing the programmer's assistant [28.4.15] ....... cc ccc ccce cece sence ee eeeaes , 1020 

Correcting ‘errots via D WIM [2814.7] cadiesccsaceawes cn khaa co Paw eeernns sakes Fane ee 1014 

Editing 2: previous eveitt (285453) 3:50.50 04-20nag ret 0bs ode ESS Ste ev edad eee eh ess 1010 

Forgetting side effects [28:4:10l 9) aac hasatcwnasuse nsears0sba5 16568 aa keakaaanems 1018 

Preventing history list recording [28.4.16] ......... 0... cece eee e eee eee neues 1020 

Printing atom: binditigs [2854.13] « ois aj:5 6.6610 0:s0/0.6%s, 9:02 Siss6is 48 os 9:0 6 is 8S beie dss ple ace 1019 

Printiig the history list (28.4.5). iisiesectieeW nv iasdessacwwases oe ee saevaeedabeed 1012 

Printing property lists [28 AlI21 vs..c0 cca aceneqanss anes e oediies con ew ee eee arenes 1018 

Re-executing previous expressions [28.4.1].........ccceee cece cece ee eeeeeeenennees 1006 

Remembering events: (28-4500) 55.5 c55,95.9:550:3'0. 50s 5.5.23 Rae RS VATS UST 495 FHSS TOSS 1018 

Retreiving events [28:48] oiscicerd soo ed eonasees 50 aie F shes 69.60 BSF 8 18S abe BRM GND KES 1015 

Retrying an event (28:45 losis sts sccoadennesdias sgdieg das de ewes ve8 saps ateeeee seas 1011 

Saving events [28:4 5B) c.05:5.5 in.9 sieare :tieoaig acka View oo 2 wie wes Gace ble ews wie Cae ages bee's 1015 

Substitating arguments (28.4.2) sisi. 2scsescescs cesies aia cede wows seabeeeeesare ve 1007 

Undoing the effects of events [28.4.6]....... 0c ccc ee cece reece eee eeeeeeeeeeneeeee 1012 
History list 

Changing a history list’s timeslice [28.6.6] .........0ccceceeeeeeeeeeeee ee eeeeeeees 1028 

Extracting ‘a history event (28.6.4) 63: ois e.c:c00 we wise oa 00ies Kes 000d i sasic eaine wee ees 1027 

Locating events by specification [28.6.3]............cccessccccccccesecccccseveces 1026 

Locating a history event [28.6.2] '« «.0:5.0.5.015:6 6410 since bo yes tine cede die oe ete tisesine sen 1025 

Obtaining an event's value [28.6.5]........ ccc ccs e cece cence eeeeeeeeeeeeeees 1027 

Printing the history: list [28.6.8] 6.0 oc. ies cee cesecccgssccssceveosseesesnseere 1029 

Recording a history event [28.6.1] .......0..csccccccccccccsccvccecccsecensseaees 1024 

Searching the history list [28.6.7] .......ccsccccccccvecctececesscscesesssssesces 1029 

Shructure Ol TIE 44 oi ids ake wchcecie ye o See When de elon ahs 3 ola aes 26 b4R Sasa DEK Sas 999 

Updating [28:2] visa sisc cide ende0oes vbw ade ot Oobesen dee ewaWelle Cones Careaeaseres 1003 
HISTORYFIND (history index mod eventadr) [28.6.2] .........0-e eee ee eee eee e ee eeees 1025 
HISTORYMATCH (input pattern event ) [28.6.7] ......... 66 cece cece eee e eee eeeenes 1029 
HISTORYSAVE (history id input1 input2 input3 props) 

(2BSG65E) ic od annie areroeaakada weary eivie/eaieale Ser erd no Wesw ee Cade anes Lee SECA URE T RS 1024 
HISTORYSAVEFORMS, History Package variable [28.5.2] ......... ec eeeeeee eee e eens 1025 
HORRIBLEVARS, File Package command [17.2.2] ......... eee e cece cece een e eee eees 547 
HPRINT (exp file uncircular datatypeseen) [15.1.6]. .........00eee cece eee eee eee eeeeee 454 
FREAD Cle) [15 266) sia se Keesas Secor daleaie ecie s Fd 2o pvc ee eiddlened 89545 Res tea Nee a eNeS 456 
I, Editor command [19.6.24] .........ccsccceceecee cree eeeeeeeeeeeeeeeeesenseeesees 704 
1.S.OPR (name expression others evalflag) [23.4.8] ...... 6.0 eecee cece eee e eee e eee eeee 859 
ICREATEDATE, File attribute [16.4] ......... cece eee eee cece eee eee eee eee eeeeeenes $11 
IDATE (At) [29.1.1] 0. ccc cccscccccceccccecdocdeterssvccssccvscereeceesosaseses ses 1034 
IDIFFERENCE (x1 x2) [13.1.2] 2... .cscccccccccceccrerecceceteesserereesesseeenees 353 
TEQP (x1 x2) [13.2.2] 2.0... ccsccccccceceecececeeseeececncnsseeeeesseceseesenseees 360 
IF 

CLISP operator [23.3] ..... 0.6 -e cece cece erence eee e ence teense eenen se eenseees 844 

Editor command [19.6.23] .......0cccece cece cece ee ne ee eee ener anne tenet eeenees 703 
IFPROP, File Package command [17.2.5] ........-e eee eee cere eect eter teen teen teens 553 
IGEQ (x1 x2) [13.2.1] 00... c cece eee c eee eee e renee ete cence ene eneeneeneensensenees 359 
IGREATERP (x1 x2) [13.2.1] 0... e cece cece cece eee e eee e tenet ence ee en seen en enes 359 
18 0063 7) | ky | ec 359 


ILESSP (x1 x2) [13.2.1] 0... cece ceee cece rece eect teen eee e eee n en eenensececensenees 359 


1124 Index 


ILLEGAL ARGUMENT, error message [18.5] ............20cccccecceuccvcccccccecees 644 
ILLEGAL DATATYPE NUMBER, error message [18.5] ..........-2600cceecececcceees 645 
ILLEGAL OR IMPOSSIBLE BLOCK, error message [18.5] ............-2000eeeeeeeees 644 
ILLEGAL READTABLE, error message [18.5] ..............00ccceccecceeccccceceees 646 
ILLEGAL RETURN, error message [18.5] ..........000scceccccccccccccccccccccccecs 640 
ILLEGAL STACK ARG, error message [18.5]... 2.2.22... 2c cece cece ccccccccccceccees 643 
ILLEGAL TERMINAL TABLE, error message [18.5]. ...... 2.2... ccccceccccccccecees 646 
IMAG (ex1) [133722] is -osis dis inie Sis aa a:cid cas bale obo eee du Ca ae eam sais a oh Oe oo aes edlee 387 
EMAAX: (33 2 2.5 RIN) EIS. 1S) ois ig da Gives hay F.05's 08 e556 deol a oboe sede be buss Pen TE Rees 357 
EMIN (3 52 oc, SND [U3 20-5] 5 Siac 9 cies nie ware STOO 0b Rae a Ops Oe ens ae Uae etna OR OOK 357 
IMINUS |x) [1S 8.2) ois. o ats isis sds 0:8 dio:0:bie Saw sie adiaa chs aad aceeeas ee oes e RECESS Dacia sees 353 
IMMEDIATE, read macro option [14.4.5] ........ 2... cece ee cece cence cece eeeeees 423 
IMOD' Gel SoS 0.6) so vores tice bv Pe NG 5 calhineh ach ae une seis nl dave nalbat welaent obiness 358 
IN 
CLISP iterative statement operator [23.4.4]. ......... 0.2 c ee cece eee eee eee eeee 852 
Masterscope set specification [26.3] .............. cece cece cece ee eee eee nee eeees 952 
INDEX-GENERATION (index) [6.2.2] ......... 0.0.2 cece cece eee eee cece ee eeeees 129 
INEIEE Gite) [16 22214.50:45.50. 0) nate ane c.codlna See iva owias Yes ode oee dave cee ceeeeer 501 
INFILECOMS? (name coms type) [17.7.3] ........ 0. cece cece cece eee eee eee eeeneee 611 
INFILEP (file) (16.214) ohicass cc die viaiate ts, n4a dailies s'4ae0ad 0S5o544 025 hed reamed sree 505 
INFIX, read: macro type [14:45] 55 ii05.66505 o5.d05siec sine galec'e tiheada tue Sav cscs ve setnes 423 
INITVARS, File Package command [17.2.2]............. 2c cece eee cee eee eee eee eeeee 548 
INPUT (file) [1G:2.2) 5 oss oc ecicicacicciandes ois ais adie csteigiva ca5050ee0e'0550500800%s00 05 501 
INSERT, Editor command [19.6.24] ........... 2... cece ccc ce cece ee eee eee ee ee cence 704 
INSERT.STRING (x fragment pos) [10.7.1] ....... 2... cece eee ee eee eee eee neees 292 
INSIDE, CLISP iterative statement operator [23.4.4] ........... 200 e cece eee eee e ee eeee 853 
Integers 
Adding [TSE 5-52.25 sn reas sg noe aie tnees Sale ee seks ease Fa Fsss eee eee ae 352 
Bit shifting operations [13-3.2].:5:0i.o-6.2 s:o:0%3:<-0:s0s oss s00.c 0 s56 siesie oss onc cese ses seies 367 
Converting 6 [13.157] 505.sac0 phoNacas'nnc sees ese egkee teas mas sBeeswawels canes ests 358 
Definition oF 122597 sisad sos was aan % ea ence Fae See age aS eee be aaw eae VEe ey OSes 25 
eo ge een rer err rer ec TT rCr es Tere Tr ser rer rr err 356 
Greatest common divisor [13.3.4] 05.006 cisc0.e 66 oe slow slscnle cen dae vie 58s s 6s ee ca¥ew'’s 369 
Logical operations [13.3.1]... :.....2.cccscecscsccccccccstecseccecceensenenccces 366 
Maximiam OF 113,18) iso oc 8 ice 29 aS Sos FOS Hale hoes Fe O09 see spas TEE S00 yew 9s 357 
Miniisxittan OF (13.155) > 36.5 80352 cacia's cacicascaesteleeme pe cas salne decree ree dee Pesos 357 
Modulirs (1323.6) 5 ciicieres seesis asp ak tas oid wine WES a mea He owe. Ue Pegs TRS d HSN ONS 358 
Multiplying [13.1.3]... .escasssccccscdecccsccccocciocesesvcccccenscesaceceeess 355 
Negating [13/12] occ: sco dios.ce see ok 55a 05a bons eweban ecinecegine tere sees aa edieaies 355 
Predicates (13:24 ociciss:tscg6sva tacts sa esa seaweed Gee bsd dese senses soe sees aeese 359 
Ratege OF (22:1) o6 cc cise ccvieccsesccccesvvcvecesguoveeseeevesecamedseses cies ads 25 
Remainder [0321.4] oo. o.c1.5 ees naliaw sare siere ose 0:sbrew Os's 40S Sale Saba SESS Sine 5,¥ a's o0% 356 
Subtracting [13.0.2] 0\s 6sicsoicicssocc'e ods cdcedeccvicgvsevervevsrve epicitdsecdedsoois 353 
Testing for equality [13.2.2] ......... ccc cece cece ene e eee ne ere cesceeneseececees 360 
Testing for even or odd integers [13.2.3] ......-....-- cece ee eee eee eee e eee eeeees 364 
Testing for negative or positive number [13.2.3] ..... 2.6... e cece cece cece eee e ee eees 362 
Testing for a small integer [13.2.3] .... 2.2... 6 cece eee eee ee eee eee e eee e nent eneeees 362 
Interlisp 
Exiting Interlisp [29.2.1].........0.-ccee cece eee e ec ee cece ee seeeeeseneeseeenes 1034 
interrupt channel [18.4] ..........-sceee cece cere eee ee een teen nes eeeeeeneeeseeeees 639 
interrupt character [18.4] ..........0.. eee e cece cece cence ne ceececeenseneeesaseesees 639 
INTERSECTION (Ist Ist2) [6.6.2] ...... 2. ccc cece cece cece cee eee e eee eeceseesereess 166 
INVISIBLE, File attribute (TOPS-20) [16.4]. ....... 05... cece cece eee eee eee een eee eees $12 


IOFILE (file) [16.3.1] 2.0... 2. cc cece c cece eee cece eee e ete e senna seeseneeseseeneees 509 





Index 1125 


| ag A a Sede 1 Re, Ob Det ne en Ad Pe Pd en) tetra ent ad ne nea 352 
IQUOTIENT (xt 52) [13.4.4] 66. 6 icccascavccanaaaanaaa sews sas eersacedyawanana sagas 356 
IREADDATE; Pile attribirte [Ol bce s divs. aa-nag Rs Avice eases ohare dine Godse ROA YEERE ES S11 
EREMAINDER Crli52) (03:18) 0,o-tyiccons'na bedaecassabotaees Kaba des aed abla be bee 356 
IT; caestoty Package vartabis (28 S:4) 55 yan 5s cos caey ans sa aels ben Loses daada tes gees 1024 
Iteration 
DY PROG [3.7] i. paisa asics siaala gaa aks ah ae ad ReWET Sa Sato E DUE OES FASE BWR Soe 4 65 
OY MAP TN sce «cnn gieizia dsl gmarciuls viaie es gcls Ue SAH AUNT UG crews kee ao Sa OG FF ev OR 329 
by CLISPoperators:[234] io kke ca wiew'n octanls on oN scaulere san se esaeeeedes waedes 846 
iterative statement operators (i.s.opr) [23.4.2]... 0... cece eee cece eee eee e ence eeeeenees 847 
PU IMES CU USE. co MN ETB AS] 55 5 she G8 Yad b vs Ge ds RD sb acd cla Malus Gas ole ace ee 355 
IWRITEDATE; 'Evle:atitibute [16:4] ciicscisaciacese us icewd Feed ous RARE WHS bEHS ERD OES S11 
I.S.OPRS, File Package command [17.2.15]..........ccccceccee cee eeeeeeeeeeueeeuees 561 
JOIN, CLISP iterative statement operator [23.4.2] ........ 00. c cece cece cece e eee eee eee 849 
JOINC, _Editorscommand: [19:62] sc -csecdcinds eo Sos beh oes as Coat eelanes peed y ee 705 
KNOWN, Masterscope set specification [26.3] ......... cc ccc cece cece ee eee eee eens 954 
KR WOTE (expression) [3:4] 5 sctiec ces sataw cach ora's Cie Gaia HAS BGS AGS TERRES oT Wend Oa. 84.0 56 
LAMBDA, fuiction type (Bs 1))s ic.0esi semmascs cad eeieaad Sewawd case ema se aew eens 214 
LAMS, ‘compiler variable [31.2.1] ).0:5.6000:5 saseee os eWies parade sab aua wowed acdsleaesdaesan 1082 
LAPFLG, ‘compiler Variable [31,1] 55: 65:5 su so, cc0es ore ania Sivinis's so aw SGN ee ak ayaa Vd WEES 1080 
PAST St} [OSU ose §05 bak oh wtee ao de backed Sea SOS pate e es BOER TRO w Mee Aled Base 136 
LAST (File FatBly UES BOs Fo B52 SxSW ETS Fas hws Fee eee SS ose neal ERT SRO LES 406 
LASTEN (ist 10 105323) | cess a ca ashecidincs xia eine 5 erna.c Wardha nisi Sa ier Sree Sib nssiee boa. nto a vipa oe 139 
LC; Bditot command [193626) s.. cdciee x's0 ie 056 Vase S SON HO OR HELE Hee Tia eae 706 
LCPIL, compiler variable [3121)) oes aise ered 55 se aalvere sin ecvipts wed eayiace Hews nea esas 1082 
LCL, Editor commiand '[19:6.26) «.c...083.sic05co ea and odie needed ee we eae etee eed Maes 706 
LOONC (pointer Ist) (6.2.3) .oiic.c is iais cos cede sveete nesaderess cereines ned cn en beness 130 
LDIFE Uist) 1502! bst3 (6202 Uy ara isare cciateias seca ays 09.97 oa Rca eep ard aw wie, So BI twee bla ly ayer Sages 163 
LDIFFERENGE (Ist .Jst2) [6:6.0) i 0.5 o5.ce é-pacaa cud Sev Sie Daaws Ths OHA REO HER esa oe 162 
LE, CLISP operator (23.2.2) .siscnicc das asa dine vetiv ea cgtines ben te boneessensecee tes ciate 838 
LEFTBRACKET, syntax class [14.4.1] 0... cc cece cece cece eee eee een e nee eaees 415 
LEFTPAREN, syntax class [14.4.1] .......ccccccccccccceevenssseneessreneeeneeeeses 415 
LENGTH (expression) [6.8.1] ......csscccccccceccsscecsscnscscsecssseeevccveseeecs 177 
File attribute: [164] sas cece ves Geviewaeles Rive sy eole Mewes gens oHRN Hees pa Dodo. 511 
LEO (23:22) [13.5]. 2 oc cscensce eed sw dsena dab dad geeks dkine's bee Oe os oes ease 808 ve Fae 375 
LESSP Ga) 22) [93516 iciiics occu ike cae Teo eat y eed Aviano ghee Vobaed cab betens ee sae Re 375 
PETTY vs ve vse casey creed es Sees RATA AREA (Lose esos ener eade a8 ehh eee ee eewaes 75 
LI, Editor command [19.6.27].......ccc ccc eee teen e nee enn e eee eee n nese nena eeeee 707 
Line buffering 
Accessing the line buffer [14.6.3]... ......0ecece cece eee e eee e eee eee eee neenees 434 
Accessing the system buffer [14.6.3] .......-.ceeeecee eee e eee eect eee teen teen es 434 
Clearing the line buffer [14.6.2]... ....6. 620s eee e cece cence eee e eee eee e eee naes 434 
Definition of [14.6] .......ccccccce sence ence eee e eee eneeeeeeeeeeeneeeeeenees 430 
Effect on RATOM [14.6.1]......cccccee cence eee ee eee eee ences neeeeeeeeneeees 433 
Effect on READ [14.6.1] .......cccecceec cece rere scence reece eeeseneeaeeeeenens 432 
Enabling and disabling [14.6.1]. ........0seeeeeee sence een e teen eens ee eee eee nees 431 
Resetting the line buffer [14.6.4] ........:ceeeeeeeeeee eee een eee ee senses eeee eens 435 
Resetting the system buffer [14.6.4] ..sccscsccscccccseesscsesvrosescccnseneceres 435 
LINEDELETE, terminal table syntax class [15.5.1]. ......seseee essere eee e eee e eee e eens 471 


LINELENGTH (rn file) [15.6.5] ......00 ec eee eee e eee eee e eee en eee ee eee rere cereeeees 482 


1126 Index 


LISP 
Epiabecta (U2 5 Lathe cis ards sees oxen an dted alae ate Soa ee Te Ph Boe ae Pane Ree ores 5 
Portable Standard Eigen [12:3] «bcos. sc anak se elsee OSS ae aos Be Cereus welwanecinaalaw bla waar 7 
LIST (expression! ... expressionN) [3.2.2, 6.1)... i cccscsesevetsisssesscivasdenccntcscs 42 
LIV TINGS; compiler eens LSU oc aces code ca eons ed 0d BiG aaa eR a Veda ees. 1079 
Lists 
Alphameric sorting [6.7.3] ............ id HERP KD TIERED DLE WHATS CARED A RPS AG ER 171 
pppending two Hate [3°23] 5 cvciwe acer ss sey oh) a6 phates Sheba tad saeceeaghyuea see 45 
Attaching elements at the end [6.2.4] ...........ccccceececceuceeceseceeeeeeunees 132 
Collecting elements at the end [6.2.5] ........... cece cece cece cece eeeneeueueneuas 133 
*: Comparing Cres Hate [6,7 A) sos is oc ce cas ewan cons wecaw eas Wid ne ees tas stan a inede 173 
Conmatematitg Bate (G29) nos e-s.0csce. see ep HESS N ES MEA OT OTR SNSE DETR RAEN OED 130 
Concatenating one-at-a-time [6.2.2] 20.0... cece eee cece eens eenteeaues 128 
Consing an element to alist [Bi200) his carp aaaucy aoe ics ake ae ng 6.0 o51b ATU Red Se ons 40 
Copying all list elements [6.4.2]. ..... 0. cc cece eee cece eee e eee ee eeeeeeeeeeees 146 
Copying lists: 16.4.1] 33 vidas dhestas seaas von Depa abice Cavers RESTARTS FURTHER E TA 144 
Copying with reversal! [6.4.3] issc5 cca wale nein gece ae 0S go B15 ems SheTTaalelen Cavin ve 148 
Counting all Cous:[6:833] cies se Se bia hGied ees eared dake bebe wales ee desee 179 
Counting list cells. (6:8:2) oc sand ecead ca etreiirn st C50 Bee kaye He HHI ONO wT EO Ee AE 178 
Counting the CDRs to produce a tail [4.5.2] ....... ccc ccc cece cece eee eee eee ones 93 
Creating a list [Si252) 5 os cs eies. 03 a2 i108 4-404 tS Hagia SAREE RCE MD DOM ATK Ra RRARAE RATES 42 
Definition of (2.3) iv66. acs a.as:d:a nce a sae w Pe wy Od $39 9.4.9, 805 GHEE S OR BUE WE TOES ewe 28 
Determining membership in [4.8] ......... 0... cece cece cece eee eee eeeeeeeeeeeees 105 
Difference:of:[6:6:1] isd scale adie chlacadwraa Galacaae Sus oasecaeas pes saewaderumda 162 
Extracting from the Nth element [6.3.4].......... ese e ee cee eee eee e ee eeeeeeenees 142 
Extracting the last: clement: (6.370). 565.5:5:5:5-45 609i cinnce vreeie Sa ecaies Bi has wae erbe NEO Nm 136 
Extracting the last N elements [6.3.3].........cccccccsccccnccccccnccsescvcsseces 140 
Extracting the tailing N elements [6.3.2] .......... cscs ceee eer eee ee ereeeeeeeneees 137 
Finding the length of a list [6.8.1] ...........cceeeeeeeeeeeeeeees Wie RE w AO h ayes OR 177 
Intersection OF 16.6; 2)! 5s ciresisic £5 a dle op o'ess REARS oR CS OM ROHS Ot Ese eaisapbe Re 166 
Merging two lists [6;9:1] 6 o.08 ce tecSiaween sae baw oy ae yale a 50e See.de Oeaere eRe ¥ De 181 
Merging with insertion [6.9.2] ..........ccccccccccceccaccccsscevcssecscescvcees 183 
Normal concatenation [6.2.1]... .ccccevcccvcvcccecvesvccccscescscescecsesevence 125 
Numeric sorting [65712] ¢ i iie isc e435 sales oda 4 assis a Rsieaeeles ms cadaaweas Sages 171 
Removing elements from [6.4.4] ......... cece cece cree cece eee eeeeeeeeeeeeeeeees 150 
Replacing elements in place [6.11.2]. ........ 0c ccc ccc e cence eee eeeeeeeeeeeeeees 191 
Searching in property list format [6.11.1]......... 2. ce cece e cece ee ee eee eeees 190 
Sorting: lists [6,7] )oss ccsiniseisieiey 65005 hi. cia ce wala d Ma eee A DS F404 CON EN STRSTR 168 
Substituting into [6.5.1] wis 5:cis sais sacs geese eae oes eR METRE TENE As La eRe ED 151 
Substituting by association [6.5.3]........ ccc cece eee eee eee eee eeeeeeeegeeeee 154 
Substituting by pairing [6.5.4] ....... 0... cece eee cece eee eee teen ee eeeees » 157 
Substituting by segments [6.5.2] 00... .. ccc cee c eee e cece e eee e teen eee eeeeee 153 
Testing for [4:5] i...csos sve e008 dpe sige aweaed taanseusciss seeders ea sae need sens 90 
Testing the tail [4.S2] 5.00.63 s:05.003 405 cr 8S gees Bae he CUES ECE TRS PRA e eH RER ETS 91 
Untlon of (6:6:9 lsc sass cape ea cae salesatew sy e:aie0 a as Fede as 07 Ra KD Se RRR RoROTE Eee 167 
LISTFILES (files) /[17-3i4). she ass scsi ealegee dad Kad ne eis bine 4 eee dain Ree NS ei she.gs oONR SoS 576 
LISTGET (Ist key) [6.11.1]... ..cccccscscccnccecccvecccccccsvccccseencceseseveveees 190 
LISTGET1 ‘(ist Key) [6:11 1) icin s cite cee cance edinn oss See oe Mee we eae Ve ewe eae ge eee ee HN 190 
LISTP (expression) [4.5] ...csscvsscsvccrcivcdvecetdenicdeebscsdobsensesdscaardenees 90 
LISTPUT (Ist key value) [6.11.2]......ccccsccvecccccccvcccccevcccssesscsssssecesces 191 
LISTPUTI (Ist key value) [6.11.2]...... ccc eccscccccccccnccccccccccccescesecseseees 191 
LISPFN, CLISP property [23.7]. ....ccscsccccnccedcessvcnavscevsvescvecvecscoseccce 856 
LISPX (lispxx lispxid lispxxmacros lispxxuserfn) [25.2]........60. sees ee eee eeeeeeeees 897 


LISPXCOMS, Programmer’s Assistant variable [25.8]. ........0:-eeeeee sence eeeeeeeees * 939 





Index 1127 


LISPAEVAL ‘(lisixtorm Hepxith) (25.5.2) 5055s is cio an xovncucenscbasees ecdectsdecsvass 923 
LISPXFIND (history event type backup) [28.6.3] ...........cccsceececeececeeeceeeecs 1026 
LISPXFINDSPLST, system variable [28.3] .......0.ccsescesccesccsescvccccccccssvcses 1004 
LISPXFNS, Programmer's Assistant variable [25.8]...........0cceccceeccueceuaeeeeees 938 
LISPAHISTORY,, aystetn variable (26:1) ic. ovies-e chive eva hansen d aaeeend cae leaeesaanees 1000 
LISPXHISTORYMACROS, system variable [28.5.1].........ccccceeceeeceeeeeeeeeeees 1020 
LISPXMACROS 

Systeme variable 1255861]! Ssh oss 535.354 NG ERA Wan Sek Seid aE BRAGS Calo aeRO AE 903 

File: Package command [172.117 sass aaiastiins 6. ieee edd 4046.5 C44 KOREA ERAT EO RT HER $58 
LISPXPRINT (expression file rdtbl nodoflag) [25.5.7]. ........ ccc cece cess cece ene e eens 928 
LISPXPRINTDEF (expression file left ...) [25.5.7] .......ccccceee cee ee eee eeeeeeeeees 930 
LISPXPRINTFLAG, Programmer's Assistant variable [25.5.7] ...........0. eee cece eee 930 
LISPXPRIN1 (expression file rdtb] nodoflag) [25.5.7] ..........cceeeee eee ee eeeeneeeee 928 
LISPXPRIN2 (expression file rdtb! nodoflag) [25.5.7] ...... cc ccc eee eee eee eee eee wees 928 
LISPXREAD (file read.table) [25.5.1] ..... ccs cdecsec costo ereenececeaseesecagneseens 920 
LISPXREADP (fig) [25:54 oiitsicia cis cad evcsicsstaeaianes ies neeas ae aA ru aL Rats OILS HES 922 
LISPXSPACES (expression file rdtbl nodoflag) [25.5.7] ........cccceee eee eee eee ee eens 928 
LISPXSTATS (returnvaluesflag) [25.9.1] ........ 2c cece cece eee eee e eee eeeeeeeeeeeeess 939 
LISPXTAB (expression file rdtb] nodoflag) [25.5.7] .........cccccee seen cece er eeeeeeees 928 
LISPXTERPRI (expression file rdtb!l nodoflag) [25.5.7] ........c cece e eee e eee eee eeees 928 
LISPXUNREAD (Ist) [253S,0])  caiacacis 6 aca tn wid asta ar ora'ai8 S00 reaieale om oa eS Red pels Ka OR 921 
LISPXUSEREN;, variable (25.2.3) cos isc God oo CaN inc Peek ev eee seh ey oN hculg ORR Ge wegng 905 
LISPX WATCH (statistic 11):[25:9:3) 6 s:e-s:5-0 saad aainea pateeere Bd a ae ade Os ai harals. w oi ecel da neoTN Adie 4 941 
LISPXS (ist fi-vats) 125:572Al sc. 55 c cenideces seas awa pase e pasae gry es Gand MESeRaa Ree AS 925 
LITATOM (expression) [4.1] 6 i siois:0 sess sinie'se insedveseed ep ewleen oe eeeeersenererereene 82 
Literal atoms 

Definitions: (250. as sa crv stato ova sacs tee Wi RS Diy 9 Be ee Pee ne ensnneees Rae bale Kai ed 19 

Testing for [4.1] scisc ccc cecict et seb teed oad asia sad sm aeine bose O08 oMivelee peewee ees 82 
ESE Ge a) ESS 2) ids sicre e800 tecine geen cis eee GREE EI PRT RE be Gls CoseN e TEARS 368 
LO, Editor command [19.627] \a..isis asc oig5d is aero’ ste'ealsieaeis 9 she siacsere.0 ara hie eo wise pw See ales 707 
LOAD (file Idfig printflg) [17.9.1]... 0... cece cece eee cere e eect en eeneeeeeeeeneenrenee 625 
LOADCOMP (file Idflg) [17.9.5].......ccccccccccccercerececescesceevsessseusesnass 629 
LOADDEF (name type source) [17.5.8] ....... ssc ee cree cence eee e eee neeenee eee eennne 599 
LOADEDFILELST, File Package variable [17.1.6] ......... ees e cece ene e eee e eee eeee $42 
LOADENS (fns file Idflg vars) [17.9.2] .......0 cece eee ence eee eee n eee eee eeeenneees 627 
LOADFROM (file fins Idflg) [17.9.4]... 0. cece cece eee enn nent ene e nee n een eneeenenee 628 
LOADVARS (vars file Idflg) [17.9.3] ......cceeecee ence cree eee e eee e eee eneeeseeesees 628 
LOAD? (file Idflg printflg) [17.9.1]... 0. ..e cece eect e cence een cence ene e eee eeeereees 625 
LOCALVARS 

definition [30.1.1] .......ccccec cece cece cnet een e eee eeeeeenereneeerereseseneees 1056 

File Package command [17.2.2]........seceeeee reese eee ee eens e ene n ee nenen seers 545 
LOG (x) [13.6.5] ..ccccccccccccccscccvessssessetsercsceceuesereeerereereenesesens 381 
LOGAND (x1 x2... XN) [13.3.1]... ccc cece eee ee eee ete eee e ener ener erence een enenens 367 
Logarithms [13.6.5] .......sseeceeeeeeeeeeceeeeeeeeennneeeenenensceaaeneeseeaenaes 381 
Logical operations 

Conjunction [S.1].......cceeee cence ee eeeeee cern eten eee een cesn seen ereneean ees 109 

Difference [6.6.1].......csece cece eee e reece enon eeeeeeeeeeerenenenensesecetanes 162 

Disjunction [5.2] ......-+eeceeeceecseeeeseenecaneeeeerseesnsrearscsaeesseees 111 

Intersection [6.6.2] .......cceeeee cere teen ence rent ee ee en eneeneeenesnsenereanes 166 

Negation [5.3]....0.ssscerccessscsnsecsecteeseserereessensereenses sae eeeenees 113 

Union [6.6.3] ....0sceccecccccsccrccvccerecccsneseessssscesssroveeceesesonees 167 
LOGNOT (x) [13.3.1] ....ssccccccaccsssescescscccccccccesrensssscsscesenenesianes 367 
LOGOR (x1 x2 ... XN) [13.3.1] ....-cececceceseecenceseesseecresecsscseeeaeraeeees 366 


LOGXOR (x1 x2... XN) [13.3.1]... .eceeeecererecerereeeeereccsceeasaeeecseseseres 366 


1128 Index 


LOGOUT ‘Cogouthig) [29:223) i iis cade dis beg sas Re88 ey de ge hha be ode Reietee sabes 1034 
LOWER Editor command [19.6.28]...........2. cece cece ecccuccccuceceuveeuveeees 708 
LY; Editor. command [19:6:29) .cc3ssieaisic:a'a'ng 25.056 09,0 Rs 0 4 a REEDS.A WRB ek o-0ie wees. 709 
Eee CX DEES Rs 5 sis 6 cnpaaciew va ninnty¥uin Wainy SRN UNG EMOCR DAE eS ee eased seta cated 368 
BSUS RD TISS.2) Cecveinstsden bassacnaviesons tccupeaauecacksaeasaded b4nanaeas 368 
LESTFIL, compiler variable [31:1] is s.s.<s:a0s.c<5,o3.0s'sb-cale bad aed age 0d cas bac tianeevanven 1080 
LSUBST (new old Ist) 16.5.2) 5 occ cdc daw-sws 0050 cave as cabayes ye dosgedeewoveaseoaaues 153 
Ty GEIS Operator 1232.54 5 x55 oes nd 15 30s ee cee 055 Ra T Ades) we ddmasa dpabeaaseias 838 
i ah REE, LS. Ee Renee eR EIR ee Pte eB i ea ne ET iy 2 274 
M; Editor commiand:(19°6:30 5 eoic-ccciy shen sndes wu wes a ooh ena ae bends Moka eas be 709 
MACTISBE TED ca sivevaigawcnders as Otaws vos atieatadaa ewe baseoe on RGid cowed vreau ees 5 
MACRO 
File. Package command (17-2511). 69.556 65/6 5.04 69 de wielas cave sine aieaieedanaaracnmaeca 557 
Property nae (8:12). .cvcessri ci sn cicssasaw eons sated aceayeados biomes eran e 246 
fead Macro Tye [14.4 S] eves eave we evar evades dees bbs Wace ate avens eVee peers 423 
Macros 
Computational [8.12540 5556.63.45 505 SERS 2 hia eles He tied ew obs esl OS oak be ORS barns 248 
Detinition Ot [B12 Als 55955 Fo.0s0.0 Ske Vs M0) Wore ee Seu. e nese cee om ewe eo gen pales wae 246 
Expatsiog OF (812.2) \-5.6ssiascce paws iss RHE ERG Fd KAT Aas Ew ER OS & ORE ATG ETS 249 
Lambda fori [8712 9) 2 actas Suisse uPe Mele ASRS HR Ohly oielg «plas Wa eee WSOC OTE SY NERS 246 
Niawibda form (6:12.09 5:3 osscaosie sie esd orsis clots Gea eGia oN gs Kee See oa we ORE ET Tew ORE 246 
Substitution (So 6s aisie-v cis 0c os bioashioe ca Sere OS aw PDs ain a 98S hE AB a Pe sa hewand 247 
Synonym [8:1251} o 560555 ae sauce keen Rea eeS on od 0.e BOW Seale ed $053.09 Fe Pelee 6 247 
Oe TOR LD ois ataaiccats naawR aks oS OTA ESET EEK AP ERUEEA SO RADARS EAS CRONE 248 
MAKE. Editoe commaticd: (19; G:300 60s sconce evsv ic sicee i bilson w wl fil cle C ae Foie anes Reet 711 
MAKEBITTABLE (charset neg a) [10.6.2] ... 2... 0. cece cee cece eee eee eee eeeneeees 291 
MAKEFILE (filename options reprintfns sourcefile) [17.3.1] ..........2sceeeeeeeeeeeeee 565 
MAKEFILES (options files) [17.3.3] isi iccinc ccce sees es cesvaceses ese e vse oe send snees> $73 
MAKEEN: Editor command [19.632] <.0s:ccsceveenscadegaetrorrevaseases pes saneegaae 712 
MAKEKEYLST (Ist defaultkey Icaseflg) [14.7.6] ........ 00. cece cece cece eee e ener eens 443 
MAKENEWCOM (name type) [17.7.4] ......... ccc cece eee e reece eee e ee enesneeenaes 613 
MAKE.STRING.FROM.LIST (Ist) [10.1] 2.0... ccc cccccccccccccccecccceeccssecvcsees 276 
MAP (mapx mapfnl mapfn2) [12.1] oii iscsi cictets te cae ce cciecraceeesnaisase des aes 329 
MAPATOMS: (fr) [12-15] vecice swe vands pa dwewvs.ceccueeneeedonecareveledeeaiernns sae 338 
MAP2C (mapx mapy mapfn1 mapfn2) [12.1.4] ....... 6. eee eee e eee eees 336 
MAP2CAR (mapx mapy mapfn1 mapfn2) [12.1.4]... 2... cece eee eee eens 336 
MAPC (mapx mapfni mapfn2)[12.1.2] 0... .0ccsecsccsccrscsccscccsccesecsesccegeses Bde 
MAPCAR (mapx mapfnl mapfn2) [12.1.2] ......... cece eee eee ee eee e eee e eee eaees 332 
MAPCONC (mapx mapfn1 mapfn2) [12.1.3] 2.0... 0... cece eee cette eee e ee eeeeee 334 
MAPDL (mapdlfn mapdipos) [30.9.1] 0.2.2... cece eee eee reer e te eee e eee e ee eeeeee . 1076 
MAPHASH (xarray maphashfn) [11.3.3] ......... cc cece cece eee eee e eee eteeeeeeeees 312 
Mapping 
Across atoms FPQ CTS) 5 sec aoa a6 or lire Se Reis kN a Ree WUL ST Re eeN a saz eT 338 
Generic: [12 1) 5 sede Owes as ains PEG CT RET EEE SOY heh V8 OTs TIARA GEA oa sas a Ule gle 329 
On successive elements [12.1.2] ...cccccccccccccscccccccccesvevessceeecenseseess 332 
Over two arguments [12.1.4] ........cccvccsccccccccccscsscrcccsessaressssccees 336 
Returning a list of values [12.1.1] ........ccccccccccccccccceeeencceeseeeeeeecees 331 
Subsetting [12.2] s.oscevnccvecssgedsedoesdsns sed pid Vie ede res CeAeeaengnadascesee 341 
With concatenation [12:13] oi.cccic aed adcdiscuisesiee de cas tdeedscveeseseesewsneaes 334 
With printing [12.1.6]... ..2ccscccccccsrnsdasecscrsscdecsceecagcssosscoeseveses 339 
MAPLIST (mapx mapfni mapfn2) [12.1.1]. .... 0... cece eee eee eee rene een eeenenes 331 


MAPRELATION (relation mapfn) [26.7.9] ........0 ccc e cece eee eee eee nee neeees 971 





Index 1129 


MAPRINT (mapx file left right sep pfn lispxprintflg) 


EZR eva res bes cone sae ee Res kds anaes yneeh pork tle HE WaMU eva oe eee eeohica tee 331 
MARK, Edthoe commie [09.6351 6 o6.5/sc ceases dance bad anawd Senden meee es akan kas 713 
MARKASCHANGED (name type reason) [17.3.9]..........ceceececeeeeceeeeeeeeeeees 582 
Masterscope 

Analyzing functions [26.72.00 5s 5sc0cdiva es cad dinnsncas dnd shana tba een ee dveenenas’ 944 

Checking Sete [262.5137 s)ei5.c:50,58 casts a,c ns Wareaihs We erteate mae eee es Seer miaeer ates 948 

Defining synonyiis [26/7-5) | sss0c sa. aa os ad beep uae ae aa aed ec ese ecaaae aceaad’s 968 

Describing function [26.2.3] 5.2 +4,5:54 salasleaeieeg eect baw Va oO Ande o19e kRe ee ale eceeese 946 

Determining the free variables [26.7.3]...........cccccccececccceeveceeneeeeeess 967 

Damping the deisoaes (26-71) ocisicinsacenaycteas sidwsaa bs vacer se ctvcaessis 972 

Editing functions [26:24] |... ais.ccy0ks ete ars wees pea e ton haan pete vedere ade peeien 947 

Erasing the:database (26.2.2) 000i visa scdacs volasessipsdaeans acaas sane eeaasea vans eae 946 

Evaluating a relation: [2627 Th 6 cc04a.ca csia ein wie’ gia Navas § 4.8-4:000 apd daroraleg S S:b Hla Wield. 4,010" 969 

Getting a function template [26.7.4] ......... cc ccc cece cece cece cece eee eeeeeeeees 967 

Invoking: Masterscope (26.7.1) 3s vici:5s aida tiakiea cae we Rabe ga dio bia, bp OK ONS Dole 965 

Obtaining help [2652.7] 3 <s.cscs.sicew cine on Mee weet eo Ree Phare yo eal vad eae nde eee es 949 

Parsing a relation: [26.7.6] i sssics.0 ssa 6 tad tt eaiere Herds 659 od Wold A Fs He Hed se SA 969 

Setting a function template [26.7.4] 22... 0... cece eee eee ee ene eee ee eee ees 967 

Showing stricture [265253] oon g xscce cain a is 04 wiaiser gee parsing 4.8.8 Qe 41880 Oe CO AL 49 ce 946 

Specifying paths: (26.5])\..2.s:<:d:20 sive da Hes Cah rea saw AT Hed Seda boaied saOevE ETRE. 958 

Specifying relations: [26.4]. Sich. cvs 458 Gan Vee eee Ome bbee ear eed Gea RP aa eee Eee 955 

Specifving Sets 126.5) scsi ccasaacevsceas som esar heres aeETES Hooda Sanon ERAd ERNE 951 

Testing item: relativity |26:7:8) oo ciscscgccc accgedses es Reoesm HAs Ia has Hwawas aes wes 970 

Updating thé database:[26.7:10] «is 6's sciscie cate orb ean dy tae eed ates Ore one dae aoeineis 971 

Using CLISP [26;:2:6) ijk cd saw sienna sire ees. cea ctidsaavsaws sa vo and se bonasaen ease 948 
MASTERSCOPE (command) [26.7.1] ........ccccccccecccec cece eseeesseeeeseseesess 965 
Matrices 

Adding or subtracting two matrices [11.4.4] 2.2.0.6... e cece eee eee eee e eee eens 320 

Checking fora [UL.4.2)\..cxaaie cic se ccua wana dca ee se cee en Cosneen aa peieee ¥50 tee EN 318 

Defining a matrix [11.4.1] ........ cc cceee cece serene eee eee ene e ee nneeeennseeenee 315 

Dot product of [11.4.4] .......ccccccccccccvccnccceveveceeeereseeeneovessecenss 324 

Getting a matrix element [11.4.2] 00.02... 6c c cece cece eee eee renee ene e nee eeneee 317 

Multiplying two matrices [11.4.4] ..... 6.06 e cece ee eee eee reece tere e eee e eee eenee 320 

Setting a matrix element [11.4.3]........... eee e cece ence eee e renee eee e eee ee teens 319 

Transposing [11.4.4] .......cceceeee eee e eect eee e eee ee ences eeeeeeeneeseeenees 324 
MATRIX (rows columns type origin) [11.4.1]... 2.6... cece cece eee eee eee e eee ee eeeee 315 
MAX (x1 x2... XN) [13.5] ......ccccccccccccnccreecaresaresnceseconssensssereoeeee 375 
MAXLEVEL, Editor variable [19.6.4] 0.0.0... ccc cee eee e eet e eee e ee en ee eeereeereeee 688 
MAXP (x) [13.2.2]... ..ccccccccccccceccccccceeteseeesscecesesesesaeneessaeeessues 360 
MAX.FIXP, variable [13].........ccccce cece cece eee ence ee nneeneenteneeeeeeenaenes 351 
MAX.FLOATBP, variable [13] .......cccc cece e cece eee e eee nee e eee eeeeeeeeeneeeenes 351 
MAX.SMALLP, variable [13] .......0ccee eres cere een e ene n eee e eee ee ee ee eee ee ences 351 
MBD, Editor command [19.6.15] ......-.-e scene eee ete e eee e eee n ene e eer en ee eees 696 
MDIFFERENCE (matrix! matrix2) [11.4.4]... 66... cece reece eee cent e een e eee e ee naee 320 
MEAN (xarray) [13.7.1] .....seeeeeeee reer e ee ee eee ee ee eenneeennceeennereaeeesanens 384 
MEDIAN (xarray) [13.7.1]... .0cceee cece erence eee teen een n een een se ene eeeeeeeecens 385 
MEMB (x Ist) [4.8] ....2cccccececccrcesersccensencesnereesenesasssssceesseeeesans 106 
MEMBER (x Ist) [4.8].....-cssccceceecscesseeserecssesecsenercesessssencereresans 105 
MERGE (<x y fncompare) [6.9.1] ....2.0seeeeereee eee e tees ee ereeeen tenner eee eeeerees 181 
MERGEINSERT (new x oneflag) [6.9.2] ..cccccccscccnsecscnccceceererseserereeenees 182 
MIN (x1 x2... XN) [13.5] ....2.scceeeceececcsecserensccccerssecesesesssscseaserees 375 


MINP(X) [13:2:2) 000 vc cewe sia atend okie ane ceeed cad saaaee tesa ss earesGamee nes srw 


1130 Index 


RUIN GS Cx) [GSES] a: srarerate aha codia arog 5 eters Sop aceon BIN At wre RRC TS BEES WET EL Ne eIeT 375 
BAIINUIS P(x) [LS 203) y xeceisiste:deare-a da Dale Sarg sig and Soke a plan by oie beeea daiaya tena aioe a. UN aeiwae oes 362 
POLDEE LIne 5 VIMAR LEO] 00425-54008 sev Nora Walesa eee vah-y Up ne eeTeEe Reale ebameee 351 
MIN-FLOATP, ‘variable [IS] \. 0.5 vs.55.0 ein Sobek Re Re Bi0'o's slew als KIC MRAM Red auras agate 351 
MIN.SMALEP, variable [13] «6/5 5:c3s s:aacaw'd 40056600 9-41.00 VSR bask Bare 60d wales aiew'es ve 351 
MISPELLED? (word rel splst fig tail fn) [22.8.2] ........cccccccccccccsccccecceccseces 822 


Mixed arithmetic [13.5] 


MKATOM (expression) [9.2.2] soos sis.sie's.ais's cis ob aie dia odo 000d be ccdeae dale oededes 259 
MELIST (expression) [3:22] fs oi sis vaivy eine c aaa sin ouera rabies paaredaeaulyahwdieawweve 42 
MEST RING (5) [TOUR nests’ Gg Vv. slew aree ely table & Fe ANU Se Bae aim ware pea a Reloae Rh wale 275 
MOVD (fromfn tofn copyflag) [8.5] ........ cece cece cece eee eneeneeeseeuseeseeueeeus 225 
MOVD?' (fromin tof copyfiag) (5) a oias caaadsc sich sewinnvaeecndes 1e5 045 aneendecs sens 225 
MOVE, Editor command [19.6.34].......ccccccccccccccccscccscccseccsecccccccesees 714 
MOVETOFILE (dstfile name type srcfile) [17.7.7] ........ 0.0. ccc cece eee e cece eeeeeees 615 
MPLUS (matrix) matrix2) [10.4.4] oisicie siecciais a vise o:,eierera ance 4 6 ndieG.o'o bib eve e:6 wih ose ewiaiald 320 
MTIMES (matrix! matrix2) [11.4.4] .......cccccccc ccc ccccccevcevscccccsccecssesecs 320 
MULTIFILEINDEX (srcfiles dstfile newpageflg) [24.1.2] ........ 2. ccc cee eee eee ene neees 879 
IN, ‘Editor comimiasid [196.35]. os o.0-4.5 60.6.4 5.05 804 2 08g Bie Fo eds ed ba ee FeT ensue eae vilee.s 715 
NAME, History Package command [28.4.8] ........ ccc eeeee eee ee eee e een eeeeeeeeees 1015 
NARGS (fn) [87-2] é.o a5. oer cs dae De bas dens aaee Fou PRES ook ee aS STORRS RS 231 
NCHARS (atnt flag Pdtb))! [9,5] | «. 5. 55:5:5/0:6 56.0 Foo eeace ae 08 400 wid oreia neck a Riese ee Reda od be daisie ora 6: 270 
NCONC (lIst1 ... IstN) [6.2.1] 2... 0.00. cece eee eee a kikca dE bale 3/40 bab Aloe aw Raed ORs wales 125 
NCONEL Ist expression) [622504 5, sisi. tesaikla avin a ciel den pee eiieds od PeS-oae le Mek sleaea man 127 
NCONS expression) [5:20] 9 cares aca'p'eas aa nab eras s10s:d alate Dawe aad oS oraals Caine d aoudine's ws 40 
NCREATE (typename from) [27.12.4] .......sccsceccccvsccccescccccssccssescesseees 995 
NEGATE (expression) [5.3221 s.c6.si005 vis.5 099 059 vind Oe Howes Baelesinddeenes seeeemepeeun 114 
Editor command) [19.6.36] |. .5:6sic3 ccs:ais ees eee nce asad eawees 6s ONS RES a ese KEG 716 
NEQ (expression1 expression2) [4.6.6] 0.22... 00 cece cee reece eee ener eeeeeeeeeeeeees 102 
NEVER, CLISP iterative statement operator [23.4.2] ........c ccc ceeeeeeeeeeeeeeeeeees 850 
NEWISWORD (sing plural form vars) [23.5.2]........sceceesee eee cece eset eeneeeeees 861 
NEW/EN Gn) (2535.3) 55 oi wiavieticd etrtarein dante a PES Doe Bars Aine CAG Saw ee aebo wewe elie eee 924 
NEX. Editor: command: [196.371 5s ¢ 64.5.003 65 05 disjs wales WF SS CRs wE Scie G's BS Oe SHE ole 716 
NIL 
Creating (NIL) (3.2:4]] ac scsi Wi s0io's Sie Ba ee Ts tie Vinieied ea T one icine ees Velasieadea es 48 
Editor command [19:6:38] .. ccs s.0 9 o.c occ gaceg cca Sad alee sees RSS FEF HON HUSH 717 
NIGEL 0) (8:83) oa c5igs peanadeorres swe camasawsewniese poem Heneea ae were saan eee eee ae. 239 
NLAMA, compiler variable [31.2.1] ........ccccccccccnccccccccsensoceseeseeeneseaees 1081 
NLAMBDA, function type [8.1.1]... ...cccsecssescnsoscvccvccccvcesvesscvccveevecenes 214 
NLAMS, compiler variable [31.2.1] ........ccccecccecnverecversesccccccccceecnerens 1081 
NLEFT (ist nitatl) (6.3.2) sii sSatcarasosags cea cnawee as ovaw ousieew SesWanwievve fang. Oe 
NLISTP (expression) [4.5] ........00eeeeeeeeeeeee PTT PTERAT UL ree er Te ee 91 
NLSETO (expression) [18.3.1] .....csccsscocdecevedccoscvsccseeseneceseevecsereness 637 
NOESQUOTE, read macro option [14.4.5] ....... cee cece eee eee eee e teen eee e ee eeeees 423 
NOFIXFNSEST; Variable [22:5.1) ic icscscvaaia sees sadeecsevedseetecveasueuesionsees 794 
NOFIXVARSLST, variable [22.5.1] .....cccccccossccnccscescdbdcscrccsesceeeceaneces 794 
NONIMMEDIATE, read macro option [14.4.5].........ceeeeeeeeeees NEM ae eS B65 REDE 423 
NON-NUMERIC ARG, error message [18.5] ....... ccc ceeee cece eeeeee eee eeenes seeses 641 
NOSPELLFLG, variable [22.5.1] .cciccssicsscsssccsscnscacsccecccececccveveseveees 794 
NOT (expression) [5.3.1] ......ccccccccccccccevcrereessesesscsscscnscssceseceneees 114 
NOT COMPILEABLE, compiler error message [31.5]. .........e ee eee cece eee e eee eeeeee 1092 
NOT FOUND, compiler error message [31.5] ........ 6. ceeee eee eee e renee ee eeeneeenee 1092 
NOTANY (somex somefnl somefn2) [5.5] ...... 0. ccc cece ee eee eee e eee eee e ee eeeeenes 119 


NOTCOMPILEDFILES, File Package variable [17.3].........0:sseeeeeeeeeeeeeeeeenes 576 





Index 1131 


NOTEQUAL (expression! expression2) [4.6.6] ........ccccecececcccceccccecececncnees 102 
NOTEVERY (every everyin! everyin2) [5.4] 5. .cicssscccscccceccerecvccenccccovasesees 118 
NOTLISTEDFILES, File Package variable [17.3] .........cccsccccccececccseccceccecs 576 
NOTRACE, Masterscope path specification [26.5]............cccecececuccucecueeucecs 959 
FUR EE CORPRCUNNID TY) TOE MURS arin gargs 06 0b 59.05 0G bale RED KEE ED OO RCARLT NER oa RAE 142 

Ranson orien ISG Se os «ass as ceeas oecd wd aesdeg ws can aeicna done unlacedcaeudones 717 
PU SAM WEAR ee MEINE M2 ESM SUELOON OLED acai, ¥.5,0Ave saeenld dug iy MOSER Le DES Cone h vader eae 271 
NTHCHARCODE (ates 1 flag rdtbl) (9.6). 0/605 cise cicsiaa ba aaddescnne bobwsancd canis 271 
NOLE (expression 19657 la giocas. kes obs sings Rat. 085 dare neon Cewaaeintiny aw ae aitirobenes 103 
PRES LEE sare ater. 5 3 « Bip. ecn e's ROS eo Ried he eee nea as wan hie Rn Whd ooBW Neue ¢ AWE KR DO EA 25 
NUMBERP (expression) (4.250). 6:05 44.cay caswgatacvensosweisbiss wanianyerancasacdss 84 
NUMERIC-SORT (items flag) [6.7.1] i... ccccsssccccsvesevavecevensescenacseceens 169 
NUMFORMATCODE (format smashflag) [15.4.1] ........0cc cece cee cence eee eneeeenees 466 
NX Editor command: (19.6657). cco v vincve vies Hesiod. Coase nae PE Cae rok Wisaee Unlove speek 717 
NXP, Editor macto: [19.6.3 7 his i.ccis vin diicenas avy si Sias saseu edu eiee seed scaans baede dean 717 
ODDP (a0 2) MSDS e ccs d sc td canto s Seg spc sere ehe alelnis daa Sik sites CWE Mae eae 364 
OFF-LINE, File attribute (TOPS-20) [16.4]........ 0.0... ccc eee c cece cece e eee eeeeeee $12 
OK 

Break: Package command (2022.0) ou i.s6 cos sc.0csccied aonaaiucbslesiacan rdwise debaw ses 735 

Editor: command !(19,6;40] o56.o3.6:ccsccsuso wediesd equals saw dia vou eaede haw see enh ees 718 
OLD, CLISP iterative statement operator [23.4.3] 2... .... ccc e cece eee eee eee eee e teens 852 
ON, CLISP iterative statement operator [23.4.4] ....... ccc cece cece reece eee e eee eees 852 
ONEP (an-initeger) (132252)! 32 cats vases + o9a8 see's seatys dieeies oR R ee SAIER Enns aeEN 361 
OPENBYTESIZE, File attribute [16.4] ....... 0... ccc cece cece eee eee ee teen eeees $11 
OPENFILE (name access recognition size parms) [16.3.1] ..... 26... cece cece eee e eee eeee 507 
OPENP (file access) [96.3.2]. iis cosecidese guadss ose sca. tans saben sas org eeee Newser: 509 
OR (expression! ... expressionN) [5.2] .........-sceee eee e eee eee eee e eee eeeeeenenees 112 
ORF, Editor command [19.6.18]...........c cece cece cee rece teen nent eee eeeeeeeeeeees 699 
ORIGINAL 

CLISP iterative statement operator [23.4.6]....... 6.0. c ese e cece eee eee eee eeeeeee 857 

Editor command [19.6.41] ....cccscccssccccscccccccccceeesesseenrserednaeesse 718 
ORR, Editor command [19.6.42] ........ cece eee eect eee e een e eee eee nnn neeenenees 719 
OUTFILE (file) [16.2.3]... 00cscvocssscccccccvseaseseseetrsokenscsnvesscconsasscen 503 
OUTFILEP (file) [16.2.4] .....cccccssscssessssecsscresccvcccvecsrecsersssvseeeeons 505 
OUTOF, CLISP iterative statement operator [23.4.6] ....... 06s cece eee eee cere e ee eeees 857 
OUTPUT (file) [16.2.3] i. cc vccccccvescscccscvsascetewercnresesrasehesec one sssen as 503 
P 

Editor command [19.6.43] ..... 2. cc cece cece eee eee een eee e eee e erent neeanes 719 

File Package command [17.2.6]......-.eeseeceeesee seen eee e ene ene een reeetrees 553 
PACK (Ist) [9.3.1] ....cccecccccccccecrcscescenescsenertesesesceeenesssseccessees 262 
PACKC (1st) [9.3.1] ....scccccceececceeseeeesnsseenesaeeeerereseesrsceuncrae eens 262 
PACK® (lisp objects) [9.3.1] .....--ssseeeceeeeeeeeeen eee e sees eesseeeee ener nee n ees 263 
PACKFILENAME (fieldname[1] fieldvalue[1] ...) CRG Fe2) sistas Be se Ble sepa sed wesis 519 
PAGEFAULTS () [29.3.2] ..--sseccscccccececccccenecrsscncesteeasssesenerssnseeees 1037 
PARENT, DWIM variable [22.7.1]....-..-0seeeeeer escent eeeeeneenecessesseeaees 812 
Parenthesis errors [22.2.2] ......cseeeeececec cence eeeeseeeaeaeeeesenrererecareretes 782 
PARSERELATION (relation) [26.7.6] ......+seseeeeeee rece eee eneeen eens eer ten eees 969 
PB 

Break Package command [20.2.6]......-ssereeeeeere essen et eeee rere ee eeen scene 738 

History Package command [28.4.13].....--++eseeeeee eres essere te ereeeenennnnees 1019 


PEEKC (file rdtbl) [14.2.7] .....csceseeceeceeeseeneeecnceeeseereseresenseseeeseass 


1132 Index 


Performance Measurement 


Breaking down performance by function [29.3.4] ..........0cccceeceeceeeeeceenees 1039 
Rey CON SOR eS oth sich 03.55.5.5.594 8%. cs ewknd wae wo VEN HOR aden Re cpenae aieKa 1036 
Counting page faults (29,322) oi. 65s cisied sieves seeenecda sou sa seels Kaemweawwas weds 1037 
Printing the breakdown results [29.3.4] ...........ccceecceenceveeeeceuveenureees 1039 
Timing expression evaluation [29.3.3]...........ccccecee cece ee eeeeeeeeeeeeeueees 1038 
PF (fn fromfiles: fotile): [95.753] ) 6 orc acs sow hw eigee Rose Wioreie Gea 4G'e Dd hibsd Waa wine aK Re oe Beis Bikes Ss 488 
PL, History Package command [28.4.12].......cccccccccccccccecscscccecccescevevces 1018 
PEUS (at x2: 50g, XN) [13S] os sis'o aie ep ngs os ea ca G's Faso bw 4s yey Vee ew awey enna eet 375 
PLUSP (x) (032.3) cccnes gies hs oes ose Rae hae Mew tes bOC Eee ecdle bhaa Kaew aeneiE 362 
POP; CHANGETRAN word) [23:10.1] sis owiscasssasese'sadsaeasie es eeaneewe e366 se0NS> 873 
POSETION: ile 0)'(1S6235] 535556090 F220 p03 ned oo daw diel ged RES ES ve AHEM UMER US aEaE IEG 482 
POWEROFTWOP (x) [T3223] sine elec aw sd kav ib.s 9 oS ca 6 ore ele ee Aaa pale Rom/e Warne 365 
PP ol h) tnl2] se: fold) FSS 72) as cicstswasis eas co aio Pak Oe PAL Sas HRUGT He PTE eae cased bo RG 487 
PPT, Bditoe command [19.643 5 $6 20925.355.5 a6 ed 08s Tas 0d-0 Oe ee veh oe ae es Reede sabaalve 720 
PPV, Editor command [196.43] s osciniss vias ci tsiceseeaevisevavssscasacaneeasiadens cada 720 
PP*, Editor command! [196.43] | o<. 6.2060 0.00.5,5 ste. eeaw sais ldeies eo sewiaceelae’ vious solelevaieiece er 720 
Predicates 
Definition: Gh cia kisasnd Ste wad Sask bmw Har Bane ea sed se side hae outils pabicaeeseee 81 
PRETTYCOMPRINT (expression) [17.8.7]...........cceceeee cece eee eeeeeeueeeeeeees 624 
PRETTYDEF (prettyfns prettyfile prettycoms reprintfns 
sourcefile: changes): (17.8.1) ass 5.50253 5.05,000% He boSs eae RAST ITLIAT LONGER TERE 615 
PRETTYEQUIVLST, prettyprinting control variable [15.7.5] .........cceceeeeee ee eeees 491 
PRETTYFLG, prettyprinting control variable [15.7.5] ........ 2.0 c cece ee ener eee eeeene 491 
PRETTY PRINT: (fns: prettydel): [15.7.1] 5:5 0:0:09:0 1 eens. eniaieteinng 4 gabe sie 4.58.4 ai pieue’g areg aele sie’ 483 
PRETTYPRINTMACROS, prettyprinting control variable 
[AS TST eas areca sata aiecte aie ata bald APSA a Nias AKO TRAWHES HEREC IE Tas FER GARE a HST GEE 492 
PRETTYPRINTTYPEMACROS, prettyprinting control variable 
PIS STEST ccxcarecfasscotstars wing cpp tea wles UO aad ba woah OL aera a HEE RSA we BSE OR Kila PHS 492 
Prettyprinting 
Control variables [15.7.5 ) cisicecsecap dans secapaas eee nae bie sna sae tee es aoe EAS 489 
Brana Tile [15.7.3] 5 5 hve cewecccas orcas ee ook puedes FOF UERTTOLTES TERS ER. 488 
Function definitions [17.8.1] .cccdian Gow dinas eo widinne Soa gte eons selsie es waned eeines wed Rese 615 
Generalized [15.7.1] 20.0 cccccsoccicc cde dete ee dnciabedd coeamesceseetionseonsees 483 
Making a file creation slug [17.8.3]..........ccccccccccccccccevccrcccceeeenerees 618 
Symbolic files: [15.7.4, 17.8] osc acca saaisisa cccnioacw awd ada ee soo 658% mse deplete ben's 489 
Tow terminal [T5762 ve Sais iisiaes ccoaew a a0 hed, oe a ierb iw ye gies Me erdlhe ans bal eh FES 487 
PRETTYTABELG, prettyprinting control variable [15.7.5] .............. aie AleR ook UPN 492 
PRIN1 (expression file) [15.1.1]... ..ccsccccegpecnscescees sees bse baecasaseresesees 448 
PRIN2 (expression file) [15.1.2]......... 0c cece cccee cee r creer ens eeeeeeeseeseceeecees 449 
PRIN (expression file) [15.1.1]... .sdvcsovsccrsenveoscsstdeaiseteseederweseseseecs 449 
PRIN4 (expression file) [15.1.2]..........0-e eee ENTER TRC RE ON 450 
PRINT (expression file rdtbl) [15.1.3]........cccccececccccceeenecreeeeseeceeeeneeens 451 
PRINTHISTORY (history event skipfn novalues file) [28.6.8] .........6eeeeeeeeeeeeeeee 1029 
Print names 
Concept of (2.1.2). cis cians os iwde asa nea see ss ee seeds dle deca sige vee nse deeuke 21 
Definition of [9] é. csc ccvcouenscocge.0 ole age a dua e ie Peis sade saae baleen eece 60 se eles 253 
Determining PNAME length [9.5S]..........6eeece sees eee e eee ener een eeneeneeeens 270 
Extracting characters from a PNAME [9.6]........ 60s eeeeeee eee ence eeeeeeeeenes 271 
PRINTBELLS () [15.1.4] ...cccscssscccaassvcccccvesevssceeseseeessssseensscseeees 452 
PRINTCOMMENT (commentptr) [16.10.2] 22... cece cece eect teeter ete n eee anes $35 
PRINTDATE (file changes) [17.8.5]........cc cee ceeee cece eee neen ene eeeneeeeeeaee 622 


PRINTDEF (expression left defflag tailflag fnslst file) 
i; cine ae yk.) Pre Tire rr rrr er irre rari rar ik tet te eect rr tri ire 489 





Index 1133 


RANE ree CGM LEE BOON sis ok. Sey eha soe AReIe Ss La keke oie d Pua bie Seis eee 623 
Printing 
Rhotioy pent ele CURL PEAT ses. 9.as cass ted as wendkne wees ds eaasceses 401 
TES GAD eects Solas seed wed ting ba GhGa NebReGhc Os Sie ada w ine w dea es aNike 452 
CPE COTRTE ELS 28): «oc pacing nasi cece anon Cases ee Geke ke uae SeS ENOL TE es 460 
Changing floating point output format [15.4.5]............cccccececececucucucuees 469 
Changmg printicvel vie CTRL-P [94.1.9 5 soo. bo Gana vee goss ad Gadenenkenaedes 399 
Clearing the output buffer via CTRL-O [14.1.1] ..........0cccccccceceeceeceeeees 399 
Coraplen intaibern: (23.72) ois ccaneanss s ae6edad owandses vedns ea@eres Op accra eure 390 
Definitions: [1.758 2) i dsa:aa savas pew vig Paw he Pee CRONE ANTE bs Oe aE Eee OF ian 619 
Effect of tadix oh [IS.44);.. diocesan kc iiwacanndsceeaaasaawenasewisense ea aes 468 
SNe RC LEN i256 2764 a Sw sein ate aM na dW NGS ERG SR ee a nd Bod Cre DAE 622 
Fixed point nambers[0S.4,31: 236.065 snc sik aera oc ciew Hew se bh awbsie's cenwoe ee eee see c 466 
Floating point numbets:[19:4;3] cos cess pcasce aarguas veses-eeerae rh aawanevesaes 467 
Format conversion of numbers [15.4.1] ..........0ccceeeeeee cece eee eeeeeeeeeeees 465 
Function: definitions ona file [17:86] 5 0.6 sios cis cee vwaws wie danas cade dcaseeusane 623 
Numbers! [15,4] i554) co ascsiwls anion fa,5;0a Roa Siv etn Vises Obie Wee. h oe a cw hehe sds ene ke 465 
PRINTNUM fixed point format [15.4.2] ....... 0... ccc cc eee cece cece eee eeees 466 
PRINTNUM floating point format [15.4.3] ......... 00. cece cece e ees 467 
S-Oxpressions TUS Moiese. cse Wace alero-e a base Ssle- ain ae vee pales awk Sw RETO SEES ER aE REESE’ 448 
Spaces [19 200 is jc siea cas siatd3.0.4g Sota ia) $94 eS Mae gaged sah os 234 Lasee smine sages 458 
PADS [1S 25] Acad Se aS Ctra chew aidan ne oaks Sans ate ene emaes caew ene peewee Re 460 
Linusial dete Strictites (1921661) 1 sic naw ca Gav ssa esS ce eiew ew saa R eae AOR ROMER: 454 
User defined TIS US). fn2 ssc s cian crave oe Ss wey IRs Pee Pe ch es eee shee pada eR 452 
With a cattiage return, (15.153) occ ccics cea a cnds cao Seeds ey Set ee ete Genes eeaee's 451 
With separators [15.252] oc. <nicc Sor ci msi0'89 n8b FAS HS OU TAY AEM TAS OT ERAS Coe Re ewe cee 449 
PRINTLEVEL (carlevel cdrlevel) [15.3] 2.0.0.0... cece cece cece eee eee cence eee eeeee 462 
Print level 
Definition of [15.3] 5 scisicd ce cee bc Ss8s Se aw eae ok ewes Mis Riko RCS ESTERS TAD Cees 462 
Dynamically setting via CTRL-P [15.3]. .........cceeceeeeecseescecsereeeeeeenes 464 
PRINTNUM (format number file) [15.4] ....... 0... cece ccc eee eee e eee eee e eee eeeeee 465 
Printout Package [15.8] ..........2cccccccccsnccccecensceseeeeeeeesssseecsseeeees 493 
Horizontal spacing commands [15.8.1]... 2.2... 60sec eee e cette renee eee e ee eees 494 
Printing specifications [15.8.3].........:.ecee cece eee eee eee e ence eee eeeeeenenes 495 
Structure specification [15.8.4] .. 2... 6.0: eee e ee eee cence cece eee ee eee eee e teenies 496 
Vertical spacing commands [15.8.2] ..... 2... cece cece eee eee eee ete eee ee eens 495 
PRODUCE (value) [8.11.1] ........cccccccccccccceccrcnsenseseeeeccccnecernsereses 244 
Prog Forms 
Binding PROG variables [3.7.1] ...-..- 6-02 ees eee e teen reer e teen erence tener eens 66 
Exiting PROGs [3.7.4] .....--00 cece cece cece eee eee e eee seen een e ene eenn scenes 71 
Implementing a DO-WHILE-UNTIL construct (S275 os ocd s Son ache ease as kee ees 71 
Transfer of control within [3.7.3]. ........00ee cece cree eee e ee eee e eee e eee eee eeeees 69 
Variations on [3.7.2] .... 0. cece e cece eee e eee e eee e eee e teen ence en eneeeanenensenes 68 
PROG (varlst expression[1] ... expression[n]) [3.7]....... 6-0 +e secre eee cece erent eens 65 
Programmer’s Assistant 
Apprising of new undoable functions PS SiS) iconc sas dieyes th exoew gasses adage ses 924 
Concept of undoing [25.1] .....-.+++++seeereereeeseseeeeeeeee eee ereseeceestes 895 
Establishing a user executive [25.3]... cc ccceccccceceeccvecnncceceessssenssenens 907 
Evaluating expressions as if LISPXREAD {25 Si] ieia saircicieGie caste Vong Fee ee Hae Ee ESS 923 
Replacing the top-level value [25.4.2]... cccccece cree cee eteneeeeeeseeeeereceenees 913 
Substituting undoable versions [25.5.4] ccc cccesceerccecccrcrereneeeceesceesens 925 
Undoable sets [25.4.1]... ose ccsescesescweceeserscisacsscaseretscccesarecveenes 908 
Undoing events [25.5.5] ...-+-sssecsscenecerecececsencsnerteesecsccscorcerers a 


Undoing function definitions [25.4.4] ......:- eee ee eee e eee e eee eet ee eee ereeceeees 


1134 Index 


Programmer’s Assistant (continued) 


Uniotag imtpping functions (25,44). ..05.< v.0.00039 599590065005 sdeadbanncssaedeisas 914 
Undoing putting and removing of properties [25.4.5]...........0ccceccceceecceuees 916 
Undoing when errors occur [25.5.6] ...:..ccccccceccaccccccccccccccccccedccevecs 928 
Writing your own undoable functions [25.4.6]..........00ccccceeececccecceevecess 919 
PROGI (expression[1] ... expression[n]) [3.7.2] ..........0cccecceceeeeeees bees Baws ow es 68 
PROG2 (expression[1] ... expression[n]) [3.7.2] ...........ccceccccccccucccccececeevess 68 
PROGN (expression[1] ... expression[n]) [3.7.2]..........cccccccecccceccucscccceceeees 68 
PROMPTCHARFORMS, History Package variable [28.5.2] ............ceeeeeees ea aa 1023 
PROMPT#FLG, Programmer's Assistant variable [25.6]. ............00ceeeeceeeceveres 931 
PROP; File Package command (27.2.5) 5405s 600.c 59:55 04s-dns va sounds dovaeguns ea eayese 552 
Property lists 
Adding a property to a property list [7.4.1] ......... ccc cece cece e eee e ence eeeenes 203 
Assigning multiple properties [7.3.1] .......... ccc cece cece e eee eeeeeeeeeeeeees 201 
Association with literal atoms [2.1.3] .......... ccc cece cect cece eee eeeeeeeeeeeeens 21 
Changing property names [7:4.4] - 0.6 03s 60s sais oes ois cca'e'a 86 a:b W'd0 649 0a bb 86 00 99.808 208 
Concept ol Tillis ssc.ccc.cocigiv.aglase ease ieee a xls dell tiwd ea dw eh aeweetes Va ose Sie 193 
Defining a property for multiple atoms [7.3.3] .......... 0c ec eeeeececeeeeeeeeeeees 202 
Baiting OF [IG BS) 3 Fes vieieccirsease Oo ase De Rao 1S Pub UMN WES Meds oed eet hes Geass 668 
Extracting a property sublist [7.6] .........sccsescesccccevsucevececcesseseceseceere 211 
Getting a property (722) custsactinsg3G0n ens Ras ws ons dik a hiss RRR WE Cee Oke e—Aes 195 
Géttitig the property list (72-0) s.o52.anessineces.ns 580508 vier bec. cee 52 des alist eae Res 197 
Obtaining the property names of an atom [7.5]........ccseeececee cece ee eeeeeeeeeus 210 
Obtaining the system property names [7.5.1]..........ccsee cece eee eee eeeeeeeees 211 
Putting properties (73) 5/5. 520%, sce sry 2.8'9:0:9/2.9:0'4 9.99 609 Hoe E ITT TES. CUR PER aS 4G KOb oe Nee 198 
Removing a property from a property list [7.4.2] .........ccceeeeeeeeeeeeeeeeeeues 206 
Removing the property list [7.4.3] .......cccccccccscscccdcsvscsecccceccesccscees 207 
Scone OF 70ST a sixiaisid.a- 6 owes kes 6 oss sae ove 858 Fees Ce dG esas, AUREUS Oa NH seine 194 
Setting the property: list (7.322) 05.6 si6:< ase cia soit 60s oisja odie a 886 8/34 e's sik Tig e OS DEWALT! D 201 
PROPNAMES (atin) [7.5] sic studs oie oss 98:5 0 05.9 aces 8.0 belly B Rg a Valero peeing ee NAN HERTS 210 
PROPRECORD, Record Package declaration [27.6] ..........0ccceeeeeeeeeeeeeeeeeees 986 
PROPS, File Package command [17.2.5]........ccccscecccsscccccvcccccccccsscsnsenes 551 
PROTECTION, File attribute (INTERLISP-10) [16.4] ........... cece cece cece eee e eens $12 
PROTECTION VIOLATION, error message [18.5]......... 20 cee ce cece cece ee eeeeeeeee 646 
PUSH, CHANGETRAN word [23:10.1) 5.5 ccasicssssascrccsectecvestectccsdcctveses 872 
PUSHLIST, CHANGETRAN word [23.10.1] ......ccceceeeceee eect eeeeeeeeneeees 873 
PUSHNEW, CHANGETRAN word [23.10.1] 02... cece cece eee e cette eee ee eeeeenee 873 
PUTASSOC (key value alst) [6.10.2].......ccccccccccccccsccscccccccscsssccccssesses 186 
PUTD (fn definition) [8.4] o....cccccseadsadsscvecccccesescccsessccseeseseeseosesne 224 
PUTDEF (name type definition) [17.5.2] .........0ceeseeceecceeeeeeeteeeeeeeeseeeees 593 
PUTDQ (fn definition) [8.4.1] 0... cc ccc ccccccccccccctecseccccevesesersecceesesenes . 225 
PUTDO? (fn definition) [8.4.1] ..0.0.0ccccc sisescess evicted nib atesdeeecavlestesasereenees 225 
PUTHASH (key value xarray) [11.3.2] ...........cccccccccccecccerereeereerseeresees 310 
PUTPROP (atm property value) [7.3]..........scccceccccceeccsceneenscccesunecscees 198 
PUTPROPS (atm propertyl valuel ...) [7.3.1] .......ee cece eee eee e cece eeeeeeeeenes 201 
Q, Editor command [19.6.15] ......ccsccceccecccccccccvccccccereeeseeseesessseeees 696 
QUOTE (expression) [3.4] ........ ccc cece cece e cnet renee seen ee eeeneeeeeneneeeeaseens 53 
QUOTIENT (21 22) (13.5) oisa3 cence eden see dans aed cee cc endereyrectinege Coeeeeeab ca 375 
R, Editor command [19.6.44] ....... cece cece cece cece eee teen eee eeeeneeeeeeeeeene 720 
RADIX (n) [15.4.4] «occ cs cccecccc ee seces c0c5e baie ee OF bride ods 0 0s 6556659 eee ob e rere 468 
RAISE (flag ttbl) [15.6.4].......ccccceeesereeenceeeeeeceeee govecberseseseeseetions 480 


Editor command [19.6.45] ....... ccc cece eee cece renee eee eee e eee eeenneaneanee 721 


Index 1135 
SRPNeAeD AMOWE MPDONT ERG GLO la 5.0 cox Saks aires Das di Sen ae Ba ER Sowa Che ai aides 382 
RONAGM, WUMGOL ROMERO TASB GI oie s5. cscs, 200s 0006s Gav a ead. Lame walk ek beGak ua beak 382 
EERE CENIG) ERGO odN sy oo Bers74- poy: orhce R04 449 Basar 8g ha BH AML EN ER ATS Nad LarewaRt 523 
tall ee DEON 3) OOD AA SS een} em eee ee MCh Con me emen Eyer a? 382 
AR eek CE) VERRAN asa sais ineln wiciesha big. co wis aloud oe Hea TEER OREN ER GT ew hana TRE 403 
RAD ae le CARI) [PADD 550 rc sen hic Varese bb 4 cuschbaeden obs un cecavchadesdnenbess 402 
PATOMS Cater File NE) (PED D: ae ¢ace des che SoG Ooo ae do hacienda ban sh diaraeeaaaind 402 
WORE HOMME TID GAT csr cctuslaa 6458 b he 6EAE HEARST ROCERG FORE T HOLDERS 720 
READ) ieeciniie: Vat Thay TET Ss 5a bis serena vc ae oa Ble + cewa de NaW Enver canes 395 
READ-EVAL-PRINT loop [S:8)) ova cucns acs Waonnadd ban tebbbvaacdes madadkeabea dha 237 
PEE SOD CORED) LUN Res sine ne clonic > 450d aR sod £04 RoHS Ro aRa Vode ekendarbs 405 
READCOMMENT (file cdtbl)'[16.10.20. 5. iicsacavcevcccacaseaedeanssasssaadbacdnane 534 
READDATE, File attribute [16.4] 0.0.0.0... ccc cece cece cece eeeeeeeeeusceeuuuneegs $11 
Reading data 
Entering atoms with embedded control characters 
Via CORES V [UGTA 5 o:222tievieaioead «to Gin eh his be Raa Ok) ATR 401 
Erasing the last character via CTRL-A [14.1.1]. ..... 0... c cece cece eee e eee eeeeeees 398 
Erasing the input line buffer via CTRL-Q [14.1.1]... 0... ccc cece eee eee eee eee ees 400 
Peeking ahead to the next character [14.2.7] ....... 0... cece ccc cece cece eee e ee eeees 407 
Reading atonas [142.1] o.ss:s:siscains we ee ais wees eal Give alo ¥ Kon d 0 ela Bish 4D So eww E Os 401 
Reading:a character [T4,2:5) ooia.c0.5-g led abe ee oak oele gue Ho ULD Mheledibs 6a Hale Ri ea eee 405 
Reading the ‘last:character [1452.6]. .0.4.05. cs casevcccesaecctsuese tuneessersveseete 406 
Reading a line :(14,2:8) os scdaaa dedi’ oda cae bende dees oa diwdalaieeagnedgederan nas ds 408 
Reading ‘froin. a file: [14.2.9] |... 3ao0.cn9 2 655.525 055 og 6 5 9 Hid OE Gls SHWE TO HARTI TLS 409 
Reading a string [14;2:4] piccdicsesveb eis vice crewed fine te eee Reese wes aera eee es 40S 
Reading upto an atom [14.2.2] ...... cece cece eccccnccee eee eenessceseeeuanns 402 
Retyping the input buffer via CTRL-R [14.1.1]........ 0.0 cece cece renee eee neces 400 
Skipping S-expressions [14.2.10].......... ccc cece cece ence eneeeeeeeeeeeeseeueee 410 
Testing atom demarcators [14.2.3] ....... cece eee eee e eee eee e eee n eee n ee eeeenees 403 
Testing for input [14.3.1] ....... 0. cece cece ee eee ere e eee e ene nenenereeeereenees 412 
Waiting for input [14.3.2]. ....... 0. eee e cece cece eee nee e eee eee e teen eeeeennnes 414 
READFILE (file) [14.2.9] sc c.ccc swsiccccscwsedccasedcvevercoseesseveperag ceased gaeae 409 
READLINE (rdtbl line lispxflag) [14.2.8] ....... 00. e cece cence cere eee e eee teen tenes 408 
READMACROS (flag) [14.4.7]... 0.0 cccee tent e eee e teen ene e rece ee eeeeeteeeeeneennes 425 
READ MACRO CONTEXT ERROR, error message [18.5] ....... 2 eee eee e eee eee e eee ees 646 
Read macros 
Definition of [14.4.5].......cccccc cece cece eee eter e nee eeeeereeeneeeeenenees 421 
Enabling/disabling read macros [14.4.7] .....-.s0sseseee eee rete ene en ee eeneenees 425 
Setting the read macro flag [14.4.7] ......0+seeeecee reer teen tenner este sen seecees 426 
Testing for read macro execution [V44ET) coin hea sae DEA vie eos Ge sNere erage rer ab tis 426 
READP (file flag) [14.3.1] ....0.seceeeeee cree ee ee cence cece eaeeensenceeereesaees 412 
READTABLEP (rdtbl) [14.5.1]... . 0c cece eect eee eee e nee tener etre eee eeeenneees 428 
Read tables 
Copying a read table [14.5.4] ......--eeeeeeeeeeneneeeereeeereeeeeeeeeceeeeseess 429 
Definition of [14.4] .......ececececccee cece ce een en eneeteneeeeeeneeesanrereaces 415 
Getting a read table address [14.5.2] .....-.seeeeeeeeeereeeeeeeeeeeeeeeeeeeeeess 428 
Setting a read table address [14.5.3] .....-.+++eeseeeeeeseeseeeeeeeee rr teeeeeeess 429 
Testing a read table [14.5.1].....-+++eseeeeeeeeeeeeee tees enesaeee ees eneeeeees 428 
READVISE (expression) [21.3] .....-+sseeeeecerrereneeerereereenenteenenesescesecs 776 
RRAL Coxt) [13.722] vsinccsen cas recsseasovvneg eres hewsedaahsea rans vent easiens ove 387 
REALFRAMEP (position interpflag) [30.5.1] ..cccceecccccereeerccsecccsnesesecsenes 1067 
REALSTKNTH (n position interpflg oldposition) [30.5.2] ......0eeeeeeee eee e reece eeees 1068 
REANALYZE, Masterscope command [26.2.1] ...cccvccsecresscccccnccsereesesescese 


RECIPROCAL (x) 13.7.3]. ..sseccsescevsvenerscssenecersscesaversensenesaeesgenes 


1136 Index 


RECTOOR (recontinanne) (27-20 Dosis aes s5-0cagss's sp h4n es Vaart ien oe Obean eee Keene dacs 990 
RECOPPILE (tiie CONS Sere) F30FiA Saas onc sles vince gone on atne inn eoae aR cha Eke 1089 
PORTE LAL Z5-5:4: mi's's'5.4 soon ae EE ah ile CA ace a ha REECE ORT DAAC I e Caeen 32 
RECORD 
File Package command [17.2.1] oo ic ccaiscs accernanaserevdeciecdecas ogaeetone 559 
Record Package declaration [27.1.1, 27.5] ........ccceeccccccccccccceuvcesees 975,984 
Record package [27] 
Accessing a ‘record valive [27.02 S06 9:i5s:02/si6:s2.5.6.59 0% a0.545 av Wms. we keb dears aelany 992 
LORE T'S TOCORAIED 7.2) Soi.a. 5 smo .6c.di eoesie eel ave we ORLA DHE URI bos OR Ae ed te aR’ 979 
, Editing a tecded Geclaration:| [27.020]. csaciau see d/altnaes Lasasnws-oeea any 60 obhvoviee 990 
Manipulating record fields [27.4] ........cccccsccccccvcccccccccccsccevcceverecs 983 
Obtaining a record’s field names [27.11.4]............. rapa abiare rah avalavaca (Goel aearetaipvetans|aiseb 992 
Obtaining the declarations of a field [27.11.3].......... CECE TET PUNTO Teer TT 992 
Obtaining the record declaration [27.11.2]........... cc cece ccc ececccceeeeeceaees 991 
Record declarations: (27.1). <2 aissinig yd) pass eewcrs eis dee dua Giad dad Able eda Wa wads es 975 
Record subfields (27 0240 x sisd sta.e'acawia piaiae $isloh acealee enn 85 4 eee bh Wwiha hale aad whale 979 
Record tale (27 ReaD sie accidins mv ae wae rele .ce whe oe RES aCe Ce oem avian Heceba eae arte 975 
Replacing a record value [27.11.5] ....... ccc ee cece cece cece eeeeeeeeeeeteveneee 993 
Resting for cecords (27.30 s0sc asic ywite 619.453.5456 -ans4 bes ayes Hb.a Pa Sle S aia oO. 8 Hoe Rae es 982 
Translating the record declaration [27.1.3] .......... cc cece cece eet e ete e eet ee tenes 978 
Using the record declaration [27.1.2] ......cccccccccccsccccsveccccccctccssaccecs 977 
RECORDACCESS (field value type new decl) [27.11.5] 2.0... . ccc cece cece cece eee eeee 993 
RECORDFIELDNAMES (record) [27.11.4] ....... 0... cece eee eens er er rer ree 992 
REDEFINE?, compiler message [31.1].......cccscccscescccvscvccevcsscsegecsivsense 1080 
REDO, History Package command [28.4.1]......... cc eee eee eee e teen eee ee eee eeeeees 1006 
REFERENCE, Masterscope relation [26.4] ......... 00. c cece cee cece cece ee eeeneeeeenee 957 
REHASH (oldarray newarray) [11.3.2]......... cc cece eee cece eee e eee eeeeseneeeeees 311 
REELS TR (position) [3017.2] eo cis disie's ois Bald caddie. a caidiag ada iere hate S Raid we nab oralbis'es Gals ¥s 1072 
RELSTRP (position) [300721 se sieicie les 55,3 55:5-3.50083 Gls si od. FEE RG ROS RET RENO MNES BEST 1072 
REMAINDER (20:x2): (RSS. oicresce sin since ooe scteveei Wik © tree alata nie els Sins ee ute eka 8 eld eleven 375 
REMEMBER, History Package command [28.4.11] ........ ccc ceeeeeeeeeeeeeeeeeeeeee 1018 
REMPROP (atm property) [754.2] .4,00.003.s/ricsie sie ba ieee cade ee an gang Sle nome g ese aearenie 206 
REMPROPLIST (atm proplst) [7.4.3]... 0... cece cece eee eee e cence eee teen eee ee eens 207 
REMOVE (x let) (6:44 Mie o.caw 2503, set aeric Saxe trove bine bie aide OP Me SS RE AFT WEN THREE THE 149 
RENAME (old new types files method) [17.5.9] ........cceseeee cece eee eeeeeeeeeeeeees 600 
RENAMEPILE (oldnew) [16.6.2] ) o.< a.chss.o'vc.e)s vies asin tisth dette sek ae Mis «ahh die vale gielew ais 518 
REPACK, Editor command [19.6.46]......... ccc cece cere cece eee rene eee ewe eee eeenee 721 
REPEAT, History Package command [28.4.1] ..........c sce c cece eee e eee e nee eeeeeees 1007 
REPEATUNTIL, CLISP iterative statement operator [23.4.5] .......0c eee ee ee eeeeeeeeee 856 
REPEATWHILE, CLISP iterative statement operator [23.4.5] ........:eeeeeeeeeeeeee ss 856 
Repetitive execution [8.10] ..........00 cece cece ees Tale’ cdlales ROS MGhin eke Slaw Bok RAW SS 2 241 
REPLACE 
Editor: command [19.6244] ois access 0b.d Kee Meee Niece tine 0b Ob469.5-0 ad See meses s ew eae 720 
Masterscope relation [26.4] ........cs ccc eee cece rete eee e eee eeeeeeeereeeeeeeeees 957 
REPLACEFIELD (descriptor datum newvalue) [27.12.3] ........seeeeeeeeeeee eee eeeees 995 
RESET ():[18.6.2)  cisiis, 0.0 cca ns caine oils 8a 5.098 6.0S a Hem did AGS Tiss dae Hea bis ws RENO Oe WHE OS 653 
Reset Package [25.7] ....:.sccsvcnccsdpecsssdedrcrecrdsesesvevecvrsdsersssesehiwne 931 
Establishing a reset list [25.7.1]. .......cceccccccccensceeeescenecsenceneenesonss 931 
Establishin undo information [25.7.5] ........ ccc cece eee eee ee ee eee teen eee eeeres 936 
Resetting expressions [25.7.4] .........cececeeeecceseensceneeneeeeeaeneeenseees 935 
Resetting variables [25.7.3] ........ccccceccceercescesceceseveesecsseeseesenens 934 
Restoring your environment [25.7.2]......-. sees eee eee e eee n eee eee e eee e teen enes 932 
RESETFORM (resetformx expr[1] ... expr[n]) [25.7.4]... 66sec eee cece rece eee e ee eeee 935 


RESETFORMS, Reset Package variable [25.7.6] ..........scceceeeeneeeeeeereeeeeenes 937 


Index 1137 


RESETLSE orm UT... CoCHibaly [25.901 1s 6's ac law sudo d¥ ante aabian dpb kad oEXE Av aeN 931 
SORE POs SEED PATON pei ee as ROM ase Nobel Ce be ewe. oat oem oe 932 
ees EnD A ERUOe EUROERY PEE CRORES PLS IGE a oi, 8c. ch 205 wehbe ucewe cb anuumsgeaamne cs 474 
RESETUNDO (expression stopflag) [25.7.5].........sceccccecsccccccceccccvcesevcess 936 
RESET VAR (var value cupmession) [25.7.3]. <5 «.scioeecssnceunneaexnn sey cn cucirceaneyes’ 934 
RESELVARS (varelet exprvesions) [25.9.4] <0 5550 gases dns vcccae ved waesbaswakeneseeaer 935 
RETAPFLY (position finarge flag) [S081 6s oici6 oi a-5.3. 200 0000%.05 6 dares ea usevl sl vewets 1075 
RETEVAL (position expression flag) [30.8].............0cccececcceccccccvcucucucuces 1075 
RETEROM (position value fag) [30,8) ois o e:anss <5'6:5.00-2 99254 6c s wapees-<r ae'oneo vkedeN ow 1074 
RETRIEVE, History Package command [28.4.8] ...........cccccccccccccccesccceccees 1015 
RETRY, History Package command [28.4.4] ..........ccccccccccccccecccecceueceuees 1011 
RETTO (position valde flac) (30.8) sz so. 0r6 scares Senivwis Sct Oe alee ae haekeantceteeeee 1074 
RETURN: (exBtession [S574 6. viccos5:e cssiete D packs x wre bos Seal Fiasen eas Able Rats Hebe alsisla Sale ie 71 
Break- Package command: [20;2:3) |;.¢:s.« 'v:010.sio(xie cis-elewleo gil 00s ary ae Galen's aWamhnins 737 
RETYPE, ‘terminal table'syntax class [15:5:1] 6665 605 60300 oc sad00s esa vow ec swee ieee art 471 
REVERSE (expression) [854,31 (3:5 5.5: dccaceie civ adcrae bmayh bu 4 So aes Se aia ey baa ped ee alee 148 
Ri Editor-command (1S: GiA 71, vci0.9 05.525 Ses Ronee Ge cee Ada oe oR aces sR es eoe aces ees 722 
RIGHTBRACKET; syntax class (14:41) sieies do s.xazauina na dnes as snow sees oigange snes OF 415 
RIGHTPAREN, syntax class [14.4.1] .....cccccusecevecessevvcdedetescvecscecescuece 415 
RO, Editor command! [19:6:48]) ..i.4-65:0 sieieaerescoiacw Sala db bo: dyad o a.s-ee be bod area delesiowss nes 722 
ROUNDED (x) [ISTSlivsctvs. gee thade ssc abpsenseG nveyedaeies eoulne dy eeaue baaeee yee 392 
Rowndine (15 7e3) ss dare sativa ip 3sie vie ow bts aibloee masa gies hese TR WO ele Sak ale om wees 392 
ROUNDTO\(x:¥) AS7 Bescaccotenegag coe ckataeseltpewsap crane aae segassen en ney aaies 392 
RPAQ (atm expression). [3:951,25.4.1] soo. csiscc vec cececies see 000040 nceed soledueblesworeas 77 
RPAQQ (atm expression) [3.9.1,25.4.1]......cccceccceccscsccccdsdecsesctoverecvesens 77 
RPAQ? (atm expression) [3.9.1] ......00csdepceccecvevesdeseneceeaeeeeses ences nesedes 77 
RPLACA (atm expression) [3.3.1].........cccccsccccceccccecececsecnscerssessesesers 49 
RPLACD (atm expression) [3.3.2].......ccssccccscccscasccnsccecscscseecresesussenes 50 
RPLCHARCODE (x n charcode) [10.5.1] .......cscccccccccccccvcccccccccescvcsccens 285 
RPLNODE (atm expression-a expression-d) [3.3.3] ..........e cece ence eee e eee e ee eeeees 52 
RPLNODE2 (atm expression) [3.3.3] ...... 6. cece eee eee eee eee eee eee en eeneeeeeeees 52 
RPLSTRING (x my) [10.5].......ccccccecccccsncceccsceecesesssnccscvesesessceenes 284 
RPT (rptn rptf) [8.10] ....... 0. cece cece eee eet e eee tenn eee eee eee ee ee ee eeeeees 242 
RPTQ (rptn rpptex1 ... rptexN) [8.10] ..... 66. e cee e cece e eee eee cree eee eee e ene ee eens 242 
RSH (x 0) [0S .G22) sn code snc cece tccctncedeanecbwawadsnun cab on pa beas cee so ece eesne 368 
RSTRING (file rdtbl) [14.2.4] ....... ccc cece eee cece etree eee e een renee ener eeeeenees 405 
RUNONELG, variable [22.7].........0cc cece eee e eee e eee neste eeee eee eeeeenanes 810 
R1, Editor command [19.6.44] ........ 00 cee cece ee eee eee eee e ene eee e eee eeeeenes 720 
S, Editor command [19.6.49]... 2.0.0.0 cece cere cere eee eter eee e eee e eee e seen reeeeees 723 
S-expressions 
Conjunction of [S.1].......-..cceeeeeceeeeeeeeeeeeneeeennnesereeeseeeercenaaes 109 
Disjunction of [5.2] .....-..sseeseceereceeenereeenennnscsecesessessaecereeeees 112 
Negating [5.3.2] .....000sessccrseseseecedsavetessssarseceeessaesessssssserees 114 
Quantification of [5.4,5.5]........eeee cece rete eee e eee e stent eee eneeeneees 116,119 
SASSOC (key alst) [6.10.1].....- esse eee eeeeeeee ence eeceereeteeeeeeneeeeeeeesceses 185 
SAVE, Editor command [19.6.40].....--.0eeseeee eee e seer eres sete reer scene ess ssses 718 
SAVE EXPRS?, compiler message [BLD]... cece cence cece ces ceeccescccscecerereeeess 1080 
SAVEDEF (name type definition) [17.5.7]. ccc ccccccencsccrsccesesrecssesseseecerens 598 
SAVESET (name newvalue topflg saveflg) [25.4.1]... cc cccc cece eee ce es eeeseeeeeeeneees 909 
SAVESETOQ (name newvalue) [25.4.1]... ce ces cece ececcrecreerecseneeecseeesseceeees 913 
SAVESETQQ (name newvalue) [25.4.1] .. cece ee cence cc ee cer eneeeeeeecteceeeenceeces 913 
SEARCHPDL (searchpdlfn searchpdlpos) 0?) 1077 


SELCHAROQ (expression clause[1] ... clause[N]) [9.7] .....-0:e eee e cere e eee e etree teens 


1138 Index 


SELECTC (selector clause[1] ... clause[n]) [3.6.4] ........ccccccccccccceccvcccuceucvuus 64 
RAS og Ww gh 0 Eo | ee 327 
SELECTQ (selector clause[1] ... clause[n]) [3.6]..........ccccccececceccccuceccvuuceucs 60 
SEPRCASE ‘(clispfig) [16.8.3] 0 s:o:c.clas.c.9's.0s &aue-eeicie sw nied a ogiaiy alevibiele od cca ewaiarcauaan'ers 526 
SEPRCHAR; ‘syntax: class [1454.1] iy <osicos.c cwsre scnredpetiodecidcained ded sed paenannadaneles 415 
SOMA THANAOE NTS LIGA vse c aia es dats kind Kirmraw hay deen yey FOV EOP RNG Ab egeek said Sia twey 1042 
Shee (ORME CR ONEION) (SBT 65559 Evin Les 40% Heer Gm hg OEE VAT ORD TRS RE Ad eta CRORE ORE 76 
Masterscope relation: [26,4] \.6.6.66i64.4 o:c65si0.000beediwwide oaeacin aes canis ceseesvacade 955 
SETA (array index-valtie) [11.2.5] oisceiea oaais dias sigalsiee'acd a'aia'e at vies o.0'0,4)4 velo ste burb,eie.ewe 302 
SETARSG ‘(vara ti vale) (857-5) .d oes a5.ac. 5.0'h 9:0:8 4:0: 9-00 0aye.0e 60 ere brain a on Sie vise aioe fe ibis 236 
SETATOMVAL (atm expression) [3.9.2]............ miaracela wh wand RiaTe Aid ro lara cbvauwid abiarainte Bee AG 78 
SETBRK (ist flag rdtbi)'[14:4.3] is isscicina snd saa caaaeadiegecsiee geass ad ahaadddawnbeeape 419 
SETCASEARRAY (casearrayx fromcode tocode) [16.8.3].........cceeeeeecccuceceeeees §25 
SETD ‘(array index value) (12.2.5) .iiccscds cd aate cd scams casas aae den dKoaweanasadaeaaate 302 
SETERRORN (number message) [18.6.3] .......... cece eee ee cece eeeeeeeeeees Pere 654 
SETFILEINFO (file attribute value) [16.4.1]........ 0... ccc cece cece cece eee ceeeceuees $13 
SETFILEPTR (file address) [16.8.1]......... ccc ccc ence ceccucccccveuseecsceeves eer $23 
SETEN; CLISP property [23.67] 0 'sasiscs d8:8 8 1s-niee aie base con easter le a RO w Sw Ald pele dO acti wine 866 
SETLINELENGTH: (nn) [15.6.5] «6:6: acess: Sere t:sre aon. 8 ous w dw els lblere b he Aiea a bloneala ea bared 481 
SETM (name row column value) [11.4.3]. ......... ccc cece cece cece tec eeieeeceeuceeces 319 
SETPROPLIST (atm expression) [7.3.2] . 0... ccc cece eee c cece cece nee e ene e eee eeenae 201 
SETQ ‘(atmmexpression) 13:8) 5.3.5: sion dos Saari paiass doa wenatsre etalae sarineW ss EERSTE Ese He 76 
SETQQ:(atm expression) [3.8] 50:0 :0.s.0.5.4.0,a-c50 018. 90.0 1.908 wine9 98.98 wed reegieylonyige 408/90 0's 76 
SETREADMACROFLG (flag) [14.4.7] 0.0... . cc cece cece eee e eee e eee eeeeeeeeees 426 
SETREADTABLE (rdtbl flag) [14.5.3] 2.2.0.0... ccc cece eee ence tent eee eee ences 429 
SETSEPR (Ist flag rdtbl) [14.4.3] ........ 0. ccc eee ee eee fee Vad ge SReC pa Sanden eates 419 
SETSTKNAME (position name) [30.3.2]...... 0... ccc c cece eee eee eee e eee en eens eeees 1063 
SETSYNONYM (newphrase meaning) [26.7.5]........ 0. cece eee cece eee e eee eeeeeeeeees 968 
SETSYNTAX (character class rdtbl) [14.4.3] 2.0... .. cece cece cece eee eee eneene 419 
SELTERMTABLE (t6b)) (3S25221 sccds dso caap sce oes heats aaseaVeeaes Fess RS UNRKHEOE 472 
SETTEMPLATE (fn template) [26.7.4] ....... cc cece ccc cece eee e cece eee ee eee eeeeees 968 
SETTOPVAL (atm expression) [3.9.2] .........ccccccccccccccceseeceenecsseeeeeeenees 78 
SHH, History Package command [28.4.16] .......... ccc cece cece eect eect teen teenies 1020 
SHOULDNT () (18.624) icias ccesc nbs wee een Fas Hho 496 KESTER HELA Tease HO SB des EDO 650 
SHOW, Editor command [19.6.50]....... 0... cece ccc eee ee ee eee t eee weeeeeeeeees 723 
SHOW PATHS, Masterscope command [26.2.3] ......... cece cece cece eee e eee eeneeeee 946 
SHOWPRINT (expression file rdtbl) [15.1.3] .........cccceeccccccceeeereecreesesrees 451 
SHOWPRIN2 (expression file rdtbl) [15.1.2]. ....... 0. cece eee eee eee e eee e enna 449 
SHOW WHERE, Masterscope command [26.2.3] .......seeeeeeeeeeeer reese eteeeeees 946 
SIDE, History Package property [28.1].........c:eeeeeee eee e sent eect ee ee eee eneeees + 1001 
SIGN (x) (SS GTS) iaivceisaisisvaad naires 2b acces vg lige gir ema fys dole He HIS FE SARTO AR SS 368 
SIN (x radiansflag) [13.6.1] 0.0... ccc cece eee e eee eee eee e eee eee ee eeneeeene 377 
SINGLEFILEINDEX (srcfile dstfile newpageflg) [24.1.1] .......e see cece eect eee e eens 878 
SIZE, File attribute (INTERLISP-10) [16.4] 2.0... . 0c cece eee cere cece eee eee n ee eneee 512 
SKOR (xword tword xlen tlen flag) [22.6.2]... .. ccc cece cere eee e eee e nena eeeeneee 802 
SKREAD (file rereadstring) [14.2.10]..........cccceeeeee eee eeeeeeeeeeeeneeeeeeenees 411 
SMALLP (expression) [4.2.4,13.2.3]......0eccec cece ee ee eee eee e ee eneeeeneee ene eeeees 88 
SMASH, Masterscope relation [26.4] ..........cce cece cece eee eee eee nee eee enneeeeneee 956 
SMASHFILECOMS (file) [17.7.6] ..... 0.6 sees cece eee e eee e eee e ence eee eeeeenneaeeaes 614 
SOME (somex somefn1 somefn2) [5.5]...... ccc cece cece cece eee e nent eee eneeeeeneeees 119 
SORT (items fncompare) [6.7.1] 2.6.0.0... cece eee cece eee e teen eee e ene eeeeeeeeenens 169 
SPACES (number file) [15.2.1] 0.0.0... cece eee eee et eee eee eee een e teen eeeeeeee 458 
SPECVARS 
definition [30.1.1] ....ccsceeccsscnsdcccsrcceeeerenssesceveccessenenes Scie walae's 1056 


File Package command [17.2.2]. ,...... 60sec eeee ence eee eee e eset e renee eee eeeees 545 





Index 1139 


PET COMTOCLMS CDA eR a ive be Side tnasinay biisa dckilsMACRES Seas OO bd SS 781 
A OCMpaRy We CR UNOES EZ9 BOG sso os. vis 6.3.7 a ne. e a eyo RGSS wae WS vee ete on 795 
ae Fee td ae: ee FE ee een ee ee eee arta aoe 822 
PERG WRENN OCD 2 eae ion wae-aa'n Wig PLES < KO POEL SAY ALES RS IRE REIT 823 
eORTNS WORMOONIN PEDDIE as senaiea gg emsa ene veoas wh TIRS Cae Let Carles 802 

ae rR De, a ee Se aetna ee. me AeA Perea a rap May hire 812 
FOCI BORG LIEB sors is aka bb avowins avd bacasqie eGo lt awoedy elbow benttadk 814 

SPELLFILE (file noprintflag nospellflag dirlst) [22.8.5] ...........0ccececeecececeusees 827 

SPELLINGS1, DWIM variable (22,7.2) «6 ssiascsacssiacvesvagesiadicesvocbaassekeases 812 

SPELLINGSZ, DVWIM varidble (23,7521) ¢ visine ay as oc asdedte cae pbetndiebasens s6ne805% 813 

SPELLINGS3, DWIM variable (22.7.2]......0.ccscsccscsccccscsccscscsccccssovocecs 813 

SPLICE, Tend nuscta te TIGA, 4 ins nc baer eeeaases guns oadinesnrnee see atean swt 423 

SPLITC, Editor command! [196.50] 55.05 0s sa SEONG « Soe Sek eek goed harks a whcas eee eoes 724 

SOIR ED EO GAAD 35:35 daw sa olen sas ad aws Was AG PAGER wI6sa CRATAEERASSOSOMPETECASANIES 380 

Sduate Poot [131614] ei sais caixa ales. o lees A pee FGA kaw Oe oe REA hd Oe eae bane ‘380 

Stack 
crib Whee Seas wae 1905.20 i 5 Sed 0s Gerda eae ae ee Ss RSE eee eee SeTS 1063 
clearing: an active stack [30.73] isi5 occ atan iss eeeaiee sd bane and devas er euae eid RETR OS's 1072 
concept Of active: frame [3052:3) oi v's ae.sites ceases 's 805.95 385.29 GW APRS 3990 RPHERSS O10 1059 
COpying stack Frames (30.7. 47. ec sisie.s 'o-4.ccs oa Hao es chi eee Hs oO Sees vies 1073 
rite: §Tc| Le Ch) Mt (51 R'4 (Men SRI PRS Pars SEO ASSL SS nd Re TNS OL Oe Be An ae 1057 
distinguishing real from dummy frames [30.5.1]..........ceceeee eee e eee eee eeeeees 1067 
evaluating expressions via access chain [30.6.2] ........ceeeeeeeecceecevceecsenees 1070 
evaluating in other contexts [30:6.1) cos cccievcsssacea ges casteseesdes si sedaessacen 1069 
exiting troma‘stick: fratie [30:8] oa5ci ate 55.55 disrars pesiss «ew gs 550 FRESE T SSS Cees 1073 
finding a real stack frame [30.5.1] .........cccccscsedercdccseccccccsscencescees 1067 
locating a frame by position [30.3.1].........ccccccccccccceeserceecsssreeeeeeeas 1067 
locating a stack frame [30.3.1]........ ccc ccccsececcceececceseseeeeeesecsesssons 1062 
manipulating stack pointers [30.7] ...... 2. ee cece e cece e eee e teen eee e eens 1071 
mapping down the stack [30.9.1]........cccceeeeeceeseeneceeeeeneceseeneeeseees 1076 
obtaining the frame name [30.3.2] .........ceeeee cece cece cere eee ee teens eneeenes 1063 
obtaining the frame variables [30.4.1]... 2.0.0... 6s eee e cere cere recente ee eeeeees 1064 
obtaining the variable values [30.4.2] .... 2.6... ce cece eee eee eee cence eee eee eeeeees 1065 
releasing a stack pointer [30.7.2]... . 1.6... se eee cece cere eee e eee e eee e eee eneneee 1072 
scanning frames for atom bindings [30.5.3].........00ee cece eee e eter ence eee enes 1068 
scanning the stack [30.4.3] ....... 000s eee eee eee eee teen eee eee e eee e nnn enenees 1065 
searching down the stack [30.9.2] ........0eeeeeeee reer e eee e eee e ee en eee eeeees 1077 
stack pointer [30.2.3] ........eceee erence erence eee n eee ee een en eee eeneeeenees 1060 
testing a stack pointer [30.7.1].....-. 6. ceeee cece eer eee ee eset e nett seen eenen ees 1071 

STACK OVERFLOW, error message [18.5] ......-- 0s cece cere eee eee eee nee n eee eees 640 

STACK POINTER HAS BEEN RELEASED, error message [18.5, 1 | Re era 644 

STACKP (position) [30.7.1] .......2sesceeeeeeeeeeenereeeeeeeenceeeeneeeeeserereens 1071 

STANDARD.DEVIATION (xarray) [13.7.1]. 2.6... cece eee e eee eee eee e eee eee n ee eees 386 

Statistical functions [13.7.1]........0ee cece cece ener eee cette tense eee eeeetenaraes 385 

STKAPPLY (position fn args flag) [30.6.2] ....--+-+eseeeeeerree eset eeeeen eee eeeenees 1070 

STKARGS (position) [30.4.2] ......-++sseeeeee eee eeeceeeteen etree ceseseeceeesenees 1065 

STKEVAL (position expression flag) [30.6.2] .....--0ece secre eee eee e eect eee en ee eeees 1070 

STKNAME (position) [30.3.2] .....--+seseeeeeeeeeeccerestesenneseessceeccceeeeees : 1063 

STKNTH (n iposition oposition) [BO.3.1]... ce ccececececsceececreseceeseeeeeseeneeees 1062 

STKNTHNAME (n iposition) [30.3.2] ....-+-+eeeeeeeeee esse steer seer eenne ess eseeees 1063 

STKPOS (framename n iposition oposition) [30.3.1] ... cc cccccesseccscsessencccereces 1062 

STKSCAN (var iposition oposition) [30.4.3] .. ccc cc cece e cece cece cnet erence ee enenees 1065 

STORAGE 0) 120.7. ciss'ns cece daw avie ciation cnsnyent svaaeenenes saver ee tose yer vares 1049 

Storage 


Changing minimum via CTRL-S [14.1.1]... 0 cece eee cece eee eee en cnet eter ences 


1140 Index 


STORAGE FULL, error message [18.5].........0.cccccccuccccccccccececcvccceeceecs 645 
pee EE eg 2a A | ee ery gee er ray Oy Ane A i 282 
Sem, Comiler variable PIU 8) 6.35 ais ositece da avei¥'t wiles tend bees cowed Manadedwet arcs 1080 
STRINGDELIM, syntax class [14.4.1] .......ccccccccccccccccccuccccscevccecucecvces 415 
STRINGP (expression) [4.3, 10.4.1] .........0cccccccccccccccccccccccccceeceeeecuecucs 8 
STRMEMB (x:y)![10.4:3) 6 60s. cds. deae pees aeadiansau dawned ees aaginn baeaD bag deeclee 283 
STRPOS (pattern string start skip anchor tail) [10.6] .............0ccccccecceccceeeees 286 
STRPOSL (charset sttiitig start neg) [10.61] «605. cs 06h ses wan vciscnriondowhueeasseawawde 290 
Strings 
s Allocating a string potster [10,151] cscs dics icssesasetseeceneosewauusduecseyis 277 
Concatenating a list of objects [10.3.1]............ ccc ccc cece cece eesccacevcecees 281 
Concatenating ‘strings'[10:3] <i ssc cisacsdsivawevacsacsaaswsawsscasnt od deadgse sess 280 
Creating a string [10.0 bis ees owes Sees a aecass oGies view nao eewae Seesaw ws Seda wees 275 
Creating bit tables: [10:6.2) 5 oo ca cece are nsin wie avon eihevon eins RS, MER OAD des Laala cishaask 291 
Definition‘of (2:5) i 5 csncs ected cas vaseesies eevee Riedes cease Has ded Mead Raae RoaK 32 
Deleting from ‘a-siring [1057.2) 5 sic. cade aca av esste canvas cas Poa whe Mey ober ten aeieee 293 
Determining string existence [10.4.1] .......... cece eee cece eee eee e eee eeeeeee 282 
Extracting ‘a ‘substring (10.2.1) ) cis cas codewdsaca vias vias cerns cesses gee aes a5 86% 278 
Getting the next or last character [10.2.2] .. 0.0... cece cece cee ec eect eect ee eeeee 279 
Inserting into! a:strivig 10; 7.1] ioe scicw eee dee S48 Seb det's elds aes Fare we saps oR este ee 292 
Replacing elements of a string [10.5] .......... 0. cc cece eee eee eee cece eect eeeeee 284 
Replacing elements with character codes [10.5.1] ............ ccc cece ec eee eeeeeeeee 285 
Searching a'string (10;6) o..:6cisisa is woos cise aa-s'as BOSS'S OFS Moe Sans ODT eae ORR TS OH 286 
Searching a string for a character [10.6.1] ........... cece cece cece cece eee eee e eens 290 
Substituting into ‘a string [10.7.3] ...0...0cescersceesvceeletoveesvewsueeyiovencs ees 294 
Testing the equality of strings [10.4.2] ........ ccc cece cece eect ee ee eee ne eeenees 282 
Testing string membership [10.4.3]........... 2. cece eee cece cece eee e cere eeeeees 283 
Ttimmming: a string [10.8]; . oss accsaasasneegeaws none iG as aa snarpeeasaesaae sats 294 
SUBATOM (expression start end) [9.2.3] ...... 2. cece cece cece eee e eee eeeeeeseeeeees 260 
SUBLIS (alst expression flag) [6.5.3] ........cccceeee cece eeeeeeeeeeeeeeeeeeeeeeerees 154 
SUBPAIR (old new expression flag) [6.5.4] ....... 00. cece cece eee ee cece eee e eee eeeeeee 157 
SUBPR (expression Ist1 Ist2) [6.5.4] ........ccccccccccnccecccccccccccccccccccecccces 159 
SUBR, function type [6.11 5 cscas. csc csa cao swrenieesennanae ve eeiawed rasdaw emp ees sets 214 
SUBRS, frinction type: [8.1] v.36: cie ude casi s Meee ee Vee eee EVES We Cre Ob ees Ma eNe ve 214 
SUBRP (fi) (8.6) .ccien aeacdasnmacaes Cee atid wad RoR Koes Ree ep oad HAR RRR C HA WO MAAS 228 
SUBSET (mapx mapfn1 mapfn2) [12.2]. ......... eee eee cece ee ee eee eee e tenet ee eeeees 341 
SUBST (new old Ist) [6:51] 6 :is\5 w:sia< srcanea aatera ache oa ees Sea Rapa Ra aas misled bere tiene 151 
SUBSTITUTE.STRING (old fragment n m) [10.7.3]. ......... cece cece eee eee cece eeeees 294 
SUBSTRING (string n m oldptr) [10.2.1] 2.0... . cc cece eee cece eee eee eee e eee e eens 278 
SUBU (x) [SUA say kd cei 4 08 rae Ry aa Rees aoe ae wie re SE eee EK PA ERE ERT AIOE . 354 
SUM, CLISP iterative statement operator [23.4.2] ....... cee eet eee eee eee eee eeneee 849 
SURROUND, Editor command [19.6.15] ........ 2. cece eee ee eee eee eee eeeee agnnway 696 
SVFLG, compiler variable [31.1]. ......... 2c ccc cece e cere cece eee eee eeeeeeeenees 1080 
SW, Editor command [19.6.52] ..... ..cc0c acess ecvedveee eye reseed cereseseedeeteeates 725 
SWAP 
CHANGETRAN word [23.10.1] ....ccccccvcvcccsvescvesoccccerbesasnasaesvesce 873 
Editor command [19.6.52] 0.0.2.2... cece sec c eee e eee e cence ents eet eeeneeeeneees 725 
SWAPC, Editor command [19.6.52]......... ccc cece eee eee eee eee e ence seen seen eeees 726 
SWAPBLOCK TOO BIG FOR BUFFER, error message [18.5]. .......:eeeeeeeeeeeeees 646 
Symbolic computation [1.1.1] ......... eee eee eee eee e renee eee eee neee ee eeeeeeeneeeens 2 
SYMBOLP (expression) [4.1.1] ......-.. cee eeee cece cence eee e eee neneeeeeeeseneeeeeees 83 
SYNTAXP (character class) [14.4.4]. 0.0... cece cece cece e eect eee eee ee eee eeenneenes 420 
Syntax classes [14.4.1]........ cece eee e cece eect eect eee n en ee seen eneeeneeeneeeeeeeees 415 


Checking a syntax class [14.4.2] ..... 0. cece cece eee e eee eee eee eeeee eee eee anaes 420 





Index 1141 


MSCtciNg tiie Sy RCE Clas AAA OT woe eat eg sos dee ocaek Re Iucks dee ee ria ks 417 
oubirig Li OUI RE IONS PIAA TN 5 bl oc oad nc boy aan Aenea curek nk cannebcanitos 418 
SHE CELED OUD LROLOCED icaiane Sirs: Acasa abv xdia 4 aN Gleb Ds eRe aoaS Glos ex hs kasi i eon a 529 
STSHASHARRAY,, system Variable (11.9) 5 cis cs vieiseoguvcccedeciiccocaviacadouctwae sus 308 
CREB CAINE CLOW IAED 6: Sse 5.U Sb yn 4 6.08 y SRM Ae PRAT TIO bk a Samet neia Eben 528 
EAI AMON LAOS Shu cient a vee deaea Candy Cae kscoredaed ponicne eter paeegineebus 528 
PSEA SAD Mot ebll occeacs ban ah.0db Maken y CHRO Oee RSS bane ee an Lad ecweiecasaveaeio 211 
SYSTEM ERROR, error message [18.5] os cia cesiccacsauss veivaas cadbesdovaancaasvacs 640 
SYSTATS, Programmer's Assistant variable [25.9.4]..........cccccuceecucucvevacucucs 941 
ee SRE PECL) LEP Re witha acing dk ON ees s AKA CEMA Ah wad CAD Uae ke vlanla eh RENO 1035 
T 
Primary File |[LG.2:0)) ay sis-cnia caalacaiae ears. adkalh.s 5052 dda dad awd ORE REA SoHE aIeRS 501 
System atom 
Terminal read! table. [14.4] 55 oi.ccscind ies tedsdncias tends end bbacau satepews candasas 415 
TAB (pos minspaces file) [US.2:3] oie iscas oaleeieagieiedd allo 000d bcd ene eae eneedoaenes 460 
TALES DWIME WAR A IS T2271) sf 55 cialis wea ratses Seuss sense ein. deeb xcacare @4 Aina dn bh bal RE ED wine hee 811 
TAILP G0 1601) 14,50) sssscas cea canvas ge dv ead senawdes .8inad binds eh even e gr TENes 92 
TAILS (RiSty PAS cores. c5u 6S cals cree ee eevee ad 8 CaO Ge boon HEMIPS Rs oe CATS 93 
TAN Ge radianstlag): [13 26i.0) sys: 5: sco ore Sew site Hinde Sateen Cod selstale s divas we Sto ea cee en etlg- 377 
TFCOMPE (files) [3153.3] sce hue aasican ss vas hed Lage eamale web cod daw Sale adh Ma 4 ean dda eo a" 1088 
TCONC (pointer element) (6.2.2) 5 sis sicadiesaeseoae dot cane daenasiaas seeds Seen ee neds 128 
TEMPLATES, File Package command [17.2.16] ......... 0c cece cece cece eee eee eens S61 
TERPRE (hile NS 2) vts.ccoie.s babu ta Vawes swale anes eee Megs anparechuose eens 460 
(retrritral tatsles (25:5 |e 55 acs size sharaaia Sis a's ers arabia Cee sles ve Ring Gia nN row Here amis miRNA NLS 469 
Character deletion control [15.6.3] ......... cece ecsscccscccccnreeccscecececees 477 
Copying a terminal table [15.5.5] .........cccccccccccccnssecrsopeseseneeveeeces 473 
Echo modes [15.0.1] dson's th 50% ogis sta e Sarcarawap Raat e oaciind gee an aS mans ene 474 
Getting the echo mode [15.6.1] .........ccecere cece eee eee e ee eeee oneness eeeees 475 
Getting a terminal table address [15.5.3] ....... 666s cece eect eee e reenter eee eees 472 
Line deletion control [15.6.3]... ..oscccccsecerunscedescaevsarviacedsbemorecvogs 479 
Resetting the terminal table [15.5.6]... ..... 2.6: e cece eee eee eee e eee eeeeee 474 
Setting a terminal table address [15.5.2] .... 2... 0s ec ee cece cece nent e eee e eee enees 472 
Syntax classes [15.5.1]... ...e eee c cece eee eee erence n sence ene eeenseeeenesaenaes 471 
Testing a terminal table [15.5.4] ......6. 0 eee e eee eee eect teen teen ene e ene nes 473 
TERMTABLEP (ttbl) [15.5.4] .....-ccccccccecs cues ceeeeteecensecerenecseeseesenes 473 
TEST 
Editor command [19.6.53] 0.0.0... cc cece eee eee eee eee e nee een ee eeeeeteeees 726 
Masterscope relation [26.4] .........0eseeee eee e teen teen ene e ene nanan ener te tees 956 
TESTRELATION (item relation item2 inverted) [26.7.8] .......- 60s eee cree eee eens 970 
THEREIS, CLISP iterative statement operator feds Wh Ried Pe ree Pe Ree Sh Be ee 851 
THRU, Editor command [19.6.54] 0.0... cee eee eee eee renee eee e teen e teen en ee tenes 727 
TIME (timex timen timetype) [29.3.3] ci vevcccvscsssdsssreercccvcccvervceveserroness 1038 
TIMES (x1 x2... XN) [13.5]... cece cece eee eee e cree eect eeen ene eensan cee ereeeenees 375 
TO 
CLISP iterative statement operator [23.4.3].....-.2 2c cece eee e nsec eee ee te eerees 853 
Editor command [19.6.54] ........ceeeeceeeeeceeeeeeeeneeeenensnseceeeteceenes 727 
Masterscope path specification [26.5] ......+..sseeeeeeeeseeeeeeeenenn nen e nese ees 958 
TOO MANY ARGUMENTS, error message (IGS). . vsikie cen tp aw biniomcasiewwasenc tases 648 
TOO MANY FILES OPEN, error message FIGS]. ce cscsccecanen cavinwescedeedsowasaiens 642 
TOO MANY USER INTERRUPT CHARACTERS, error message [18.5] .......-..0- ees 645 
TRACE (expression) [20.1]......-+seeeeeeeseesreceeeereeneceresessseecssesseeerees in 
TRANSPOSE (matrix) [11.4.4] ...----- anneys 


Trigonometric functions [13.6.1, EPG sive ba beck yerga HEE ROSES ARO ERR ET SRE T 


1142 Index 


TRIM: Ceteinig) TIO 8) 5c ds ocincet week a Oona a keane can atl Cyalestenreuweeraeole sas diets 294 
PRUE) [60d cise inn Jan haveh Sad iaend ioe hoe he ROR TER EK Cob owed oats ee eeKaen «ty 28 
ERUNGCATE GS) [13;7.8)) asiesvaigad ote oan. dcgh 0on RASR As ee aie 6-Oee bean eae oR etabales 391 
MEY?) Editor command [196:55] io \55050 xis sia aalein Ge hawaie dt Hed wares ta one ee RR bade? 727 
TYPE, File attribute (INTERLISP-D) [16.4]............ ccc ccc ccccccccccceccccceeeees 512 
TYPERECORD, Record Package declaration [27.5] ..........cc.cceccececceccccseeees 985 
TYPE?, Record Package declaration [27.3]........ccssscesssccssccscsccsccccccescess 982 
TYPESOF (name possible-types inpossible-types source) 

EL PeS1 GIs wcasargcrameste ove Sion Gweie-ciaus oe pote Re AEE 0S ON Fa Tee Meee aleloe NaN bn Kae 605 
TYPE-IN?, DWIM variable [22.7.1]..............-. Rises AK Cbd Rade He seen sees eheper 812 
UB, Break Package command [20.2.5]. «400.0 siveneodocintcescevawecescocsacdsgsseas 738 
UGLYVARS, File Package command [17.2.2] ........... cece cece cece cece eeeeeeees 546 
UNADVISE (oxpronnlon) (20,2) 6.<.0:550.04 ben escnsesseadecbaseveceses saab ashexdteacaey 775 
UNARYOP; ‘CLISP: property [2327] ie:c'v-w'eisises seuss so tele Sins ec vwieree'send'e de anan sae casa te 866 
UNBLOCK, Editor command) [19;6.53] 56 oercc!icis Soa o sigs wisracte 4:06 eels Sesee owe enlace cwas 726 
UNBOUND ATOM, error message [18.5] ......... 2c cece cece cece ete e eee e eee eeeeeees 646 
Unbound atonia [22.3 1 ias5< is 5 ais avs sicinorvtace, tere Big 00s oOo aie ee Ree SSG DOE SOK BOS RR RTED wld 785 
UNBREAK: (expression) (20.4.0). 65s osicick dais sma ne hed-nev else sloa ea seg ap oa Fea Ew ERS 761 
UNBREAK IN: (iy) [ZO Sls occ S rortcate Hnee 0o-w Her5 05.6 nah. v na Calne wea Bad caistie peda ies 763 
UNBREAKO (fin) [20.420 iei6 ccaisin oe.c%sie'e oe sie Sein woba sW'n ob 06 wh hle a bes OEE ORE paw are Bw’ 762 
Undefined functions [22.312] oa issis.viese wsie 6:5'00 8D omiendie sd ce'b.te Ree paeeabeteeeeeedeee 787 
UNDEFINED CAR OF FORM, error message [18.5] ........ 0. ccc cece e cece eect ee enees 647 
UNDEFINED FUNCTION, error message 1.2) ee eee eee ek ae ere 647 
UNDEFINED OR ILLEGAL GO, error message [18.5] ........ 2. 0c cece eeee eens eeeeee 641 
UNDO 

Edito® command [19:G6,56) 5.63 sco's cs tee Kv.9 Se SO wien Mes dih eiede sel pak a6 Fab oes 727 

History Package command [28.4.6].........seececccceceeeecceceeesseeeeeneeees 1016 
UNDOLISPX: (event) [25:5.8) so cccncdecacssavcaessebsvd4ahe vee rehedaeeareasasane 925 
UNDOLISPX1 (event ag) [25:55] csieccsis.c ticnrege nen ea injec slgniclac vines teins ea ea Siaeesi oe 927 
UNDONESETO ‘(undoform)'125.5..6)) sicicicaicce'deg vionies boa aes dee Sev eass Lanne ce ceeien 928 
UNION (isthiist2) 16:6:3] 04.6. s5c.0 5 ct5a dee cbc Ree pie Poe nine Eas ae few lawev bese naesies 167 
UNIQUE (Ge) [Gi6.2] sess fis ais perkin ga bora. SWE ADA DR ORE PATH RETA TAROT RS RENE Dae SS 167 
UNIQUE-UNION (2:59):[6:G.3] 6.0 5:0.cie0.s 54.00 ahs V64G6 8 HAS.04,6. 05a alee aie wld aalginla’s age aipieeatt 168 
Universal quantification [S:4] 5 so s'55ais es aia-a sss drains: ain braidin's g/a%s ay vin nese s Hud oes wren eee 116 
UNLESS, CLISP iterative statement operator [23.4.5]....... 2.0 eeee eect e teen eeeees 855 
UNMARKASCHANGED (name type) [17.3.9].........cccccccccccccccccceeeevseceees 582 
UNPACK (atm flag rdtbl) [9.3.2] ..ccccccccccescccncccessacasesetenssnccsccssecesss 263 
UNPACKFILENAME (filename) [16.7.1] ......... ccc ee cee c cece cece cence eeeeeeeeees 519 
UNSAVEDEF (name type) [17.5.7] .....ccsccccccccccccccccnccvesseesoveresvesesees 599 
UNSET (nase) [25,415 saci a ciwieccc cas Seale So's o Ven was sae hevde eee heen sae 7s.qle ues » 912 
UNTIL, CLISP iterative statement operator [23.4.5] .........0ceeceeeeeeeeeeeeeeeeeees 855 
UNUSUAL CDR ARG LIST, error message [18.5] 00.2... cece cette eee eee eee eeee 644 
REP. ‘Baltne cosmenatel £196.57 5 oss Fay ck oe sna ba sie ss va6e SUNG SKS 50d sy acu oes eases 728 
UPDATEEN (fn evenifvalid) [26.7.10] ...... cece ccc ccc ce eee se er eeceeeeeceececeess 971 
USE 

History Package command [28.4.2].......-2cceeeeeeeee eres eee eeeeee ee nenneees 1008 

Masterscope relation [26.4] ..........ccceee cece eee eee e ee ee eee eeeeeeneeeeneees 957 
USE AS A CLISP WORD, Masterscope relation [26.4]........00eeeeeeeeeeeeeeneeeees 957 
USE AS A FIELD, Masterscope relation [26.4] .........cccceeeee eee seen eee eenenees 957 
USE AS A PROPERTY NAME, Masterscope relation [26.4]..........eeeeeeeeeeeneenes 957 
USEMAPELG, File Package variable [17.1.5]. ..........c cece cence eee een eeeneeeeeees $41 
USERDATATYPES () [27.12.7] ...cccsccccccccccccccccscccccvcccvcstessessccsccers 997 


USEREXEC (lispxid lispxxmacros lispxuserfn) [25.3] .......0seee esse ence reece ee eenees 907 


Index 1143 
USERINTERRUPTS, system variable [18.4]............ccecccceccccecccccceccecceces 639 
USERLISPXPRINT (expression file rdtb! Hodotlag) (25:54) cies ein stenogcuivaesasares 928 
USERMACROS, File Package command [17.2.11] .........ccecececececucecucececees 558 
User name 
8 AS | Rn eee 1036 
RIE ERE SP AEUERS KRIS TELOA) LOD BNE a 6.8 045. Bina Fite ae 6d eds oad Mean eoaen Loo tab iawaree eat 1036 
EISEN AS PA i COUT CENMINIS EISSN io ohn csara'n wk a.dad WECS AA WORST otek OURO TARS 646 
User syntax classes (see read macros) 
PERS a 28) SP Bog be by a | aa ee ee Oe ee 812 
USE-ARGS, History Package property [28.1] ............cccccececcccncececeecececess 1001 
ICR GES AN). LUOUe ae Pa. Te Reap ATE A Aas HATO UN DN ea OR g RE Nes RARE SAA o Edw ERD ORET ERTS 270 
DsCASEP Cay (Ss 8) icsis visie-<acy, a hiscaee aco Solis wees ACS PLE Ie dA EW ONS Rd wa tena 270 
Valuecells (2127 5:55.55 acu woes Seo oh Oe Se OE Tek. Ghee ote ooo Rise Me eG ER Sele ae 21 
Valiveiediting (19.0 Di ssp cctsse com wsedas cacewes ys da ass sees tee 4700 04 saw dagulege es 666 
VALUEOR (event):[28.6.5)] | castewaa ny 404 tid hea as 4S Vee RES OF Odes aMS ne Dower eRls 6 ghnes 1027 
VARIABLES (position) [30/431] 5:i:656.< wodnsc olvogavalas be 2G Rada sd ob SAS ba Nee aes ee 1064 
VARIANCE Grarcay) PIG e7e Dire oes x cere cists dos pores eee le wi entaw Sor a Re MEETS Res 386 
VARS; File Packageicomman [1752.2] 3 iss'nc asi cin'a ais o'cle ae saees + pag sae sa omisabies eae 544 
VAXMACRO;, property name (8212) 55.55.05 cee5 cease Ca tosaaviewabe seas capaseged Rees 246 
VIRGINEN: (ititlag) [20/523] 5-65 ssece ss te-eia e:aieses: 0-36-0590 shares! poise io 9 cp BEA Faw Sie ONG SOK Bp 765 
Virtual Memory [16.9] sisiss sisasiaeng Tac ais ibe 4 ows stan Oss 5 ape Ris besiege seas Sou ce Oa? 
Restoring [16.9.2] 35.0358 See es ack sew avatiey Ged pavqarnboneaiedeasg pees sbawaende $29 
Savin (36.94 sisi sisi s wawewead acy gas reach ena waneed po dek oh E05s Mendes hederys 528 
WAITFORINPUT (file) [143.20 54650 38 cdc tied wiend cove ee iG 19 Bed Oe ses es BeaysseMeen 414 
WHEN, CLISP iterative statement operator [23.4.5] ..... 0... c cece cece cette eee eens 855 
WHENCLOSE (file prop value ...) [16.5.3] ........ cc cceee cece eee eee eeesscenseesenes 515 
WHEREIS (name type files) [17.3.8] 20.22... ec cece cece cece eee eee eee e eee een eneeees 581 
WHILE, CLISP iterative statement operator [23.4.5]....... 0.0 e cece e cece eee e eee 855 
WITH, Record Package declaration [27.4] ........ 6. cece eee eee eee teen en enenes 983 
WRITEDATE, File attribute [16.4] ....... cc ccc ceeccccc cece ccc eeeeceeeeeeeeraeenees $11 
WRITEFILE (expression file) [15.1.7] ..... 6... e eee e cece eee cence renee eter teen eens 457 
XTR, Editor command [19.6.58]...... 0... cc cece cece ener e eee e eee e teen ene eens 728 
ZERO ().(8:8.3] i occ canst esses essteeecsocserovesecver tresses sasbbvcseswben secee 238 
ZEROP (expression) [4.2.2] .......-seee cece nee cence nese ene eee een eee een ennreeeseees 85 
Zetalisp [1.2.1].......sceecseeceeccrceeeneseeesseesesensssseoereanesseeensreeeretes 5 
0, Editor command [19.6.60].......-..sce eee eee eee eee teen een e ene een eee e teens 730 
2ND, Editor command [19.6.26] 0... 6... cece cree eee teen eee e eee n enter ee eenrecees 706 
3RD, Editor command [19.6.26]...... 06sec e eee e rece erence ere eens ee es eneeneeeeees 706 
/MAPCONC (mapx mapfn1 mapfn2) [25.4.3] cc ssecccccaicsaccuseccrovecsaseseceores 915 
/MOVD (fn1 fn2 flag) [25.4.4] «0... 2. 0c eee eee e eee e eee eee een eee n sense e eee eenees 916 
/PUTD (a.function a.definition) [25.4.4]... ccrcccccceccnseveccccsceeccccscesseceees 916 
/PUTPROP (atm property value) [25.4.5] ....- ++. seee reese e eee eee tet ee eee ee ee eennes 917 
/REMPROP (atm property) [25.4.5] ...-.eeeeeeee eect eee e eee e renee eee eeene nee eeees 918 
/RPLACA (name newvalue) [25.4.2]... ce cececceeecncseeccnceeeeeesecseeneeeeeseres 913 
/RPLACD (name newvalue) [25.4.2] ...--:eeseeeeereeeeeee ester ese teeneereneceeness 914 
<), CLISP operator [23.2. A] ncsssceusvcccpastevaed cnet edeepeseroenetsenngecerens 835 
t, CLISP operator [23.2.1]... +--+ seeseerererereertesenensonserscstesecsserenvenss 835 
1GO, Break Package command [20.2.1]... ces ee cece ecen cee eeteeneeneeseeneueeuecears = 


INX, Editor command [19.6.37] ....++seesseeeerreeseeneseeseeseceressecesareeeetes 


1144 Index 


!OK, Break Package command [20.2.1]............ccccccccccccccccecccccccucucenns 736 
TURD, Eegmae commend 10906500 scons 4 cas 539.300 5 vaohw cw been ec ne ness Socks kaw 727 
IVALUE, Break Package variable [20.2.2]. «00sec cesces scvevasciasavcssvecasivetevece 736 
10, Editor commiand [19,6:60] oso ia.ciis ca arcdiasacy tics ak eee BURRS Cale whe cons oo cQwie et xc 730 
1, CLISP operator [23.2550 sé. asa nprd%s{arasarana ais'a mary’ ms ead dows wia-eeaien/e dele weiss band howe 836 
“+ CLISP operator [23 2:2) 3 igs cag th wl ceeaideces ee ce anes cree 8s deca caeauokasadeees 837 
Me CEASE UGE 2S 2.2) 8 oun cine eek Fed hoon Uae pas cewbeas- ct oF nad eegRENOAB HUSA SS 837 
«", Break Package command: [20.2.10] 5006 ccsicseeyssecegessdasevveresenyésdssesces 746 
* 
CLISP operator: (23.2.2) a. is a4 0Sbe ees cova aed has nee ReRC SERS Ta Ede es weaE OEE 837 
" Commmpant Taectiohs [IG AGN ois ssa 'cg ving vido. de9 446 hoo oho xdae cided cared Wie aa 533 
Edstor commarid)[19.6:59) | soc. sic vs scat tise 8 6600 aU ealdle a Ra ehd 04 OCR a Uwe ed wa He 729 
File Package command) [17.2.9 sio66:5. 6.64 05.5 ses 0:s'e'ek dle wars's sewed decaeedeescewsee’ 555 
Read thacto character: [14.4.6] 0560s 60s cosnc ace d éogaees cade essence yes snowsees 424 
**COMMENT**FLG, System variable [16.10.1] .......... 0... cece ccc ccc ce ccceeeees _ $34 
*ARCHIVE*, History Package property [28.1] .........0cccccccccccccscvscccscccccece 1001 
*CONTEXT*, History Package property [28.1].......... 2.2 cece cece cece eee cece eeees 1001 
*ERROR*, History Package property [26.1] 5 «oi cecisvs coesicaassceensseebsciescesseaas 1001 
*GROUP*, History Package property, [28.1] ........... 0. cece eee cece cece eee eeeeeees 1001 
*HISTORY*, History Package property [28.1] .......... 2. cece cece ee eee ee ee eee eens 1001 
*LISPXPRINT*, History Package property [28.1] ............ cee eeeeccceceeeeeeeeeees 1001 
*PRINT*, History Package property [28.1] ............ 0. cece eee eee cece cece eee eeees 1001 
CLISP operator [23.2.2] ii aan foes cad iad esa acelrcdaas wiaes's ape ceepe wad adap bese 837 
Break: Package commiatid [20.2.9] ..5) «0 diac 6.5 500s Woo dee ods pl Ge OU NS OSs URC Oe et 745 
Break Package command [20.2.4].........ccvcccccscccercccvenvccssccsecssccens 738 
CLISP operator [232.2 1l s5 si scadis ocd crow ced cea had opie eg VU os shes Siafee dhe saSOs 837 
CLISP operator (232252) 616 sac Ort ee PAG odie CA85:0 04-09 5-09 EOE ER ARTO eRe Re 838 
Break Package command [20.2.9] «6.4.3 ¢escsaede de peacuea ars Cassese eosaedsaesses 745 
CLISP operator [23:2:2) i035 Sssispais aiaie ins decal Daste ca baa 6 a 00a Oe Ge TNS RE0 SS OH oala 838 
History Package command [28.4.15]..........0 0c cece eee eee eee e eee ee ee eeneees . 1020 
24 5'CLISP opetator (23.2.2) iscc-5 Sapa sink cana eae waierdie gel dageatee dan enaeed saadeedes eee s 838 
+ CLISP Gperator [2372.3] 00 cicrgnaiee ate a iais souks, c08-5.c on SECU SE reas FIRS REA DEE OT RES 839 
(GLISP operator [23.2.3] isc cass sale ases(e or ardeie ons eves Na oe S SRE OES OO CCT ASO PEON 839 
#CAREFULCOLUMNS, prettyprinting control variable [15.7.5].............-+-2eeeeee: 491 
#RPARS, prettyprinting control variable [15.7.5] ........ ccc eee e eee eens 491 
...ARGS, History Package property [28.1]........... cece cece cece eee eee eee eeeeenes 1001 
? 
Editor command [19.6.43] ............ peciaxe Pash esata aun snseventsa te eeaw eae 719 
History Package command [28.4.14]...........ccceccccccccccccecnessccecescsees 1019 
Read macro character [14.4.6]. ..............0005- POE ER CET EET TT eT Tee ee 424 
2?, History Package command [28.4.5] ..........0ee eee cece eee e eee eee eeeeeeeneees 1012 
?=, Break Package command [20.2.6]...........0cceeeceeeceeeeeeeeeeeeeteeeennenes 738 
«, Editor command [19.6.33]..........-..--- £58 a Oa AEDS E DES COE RES ENE Be pelearente 714 
++, Editor command [19.6.33].. 0.0.2... 0c cece cece eee eee eee e eee e eee eeee enna 714 
\, Editor command [19.6.33]........ cece ee cece ener cence eee e seen bis Soa euy NEST 714 
P, Editor command [19.6.33].........c ccc ccec cece cece eee e eee ee teense eeeeeenaseees 714 
%, the escape character [14.4.3] ....... 2. cece cece eee eee e eee eee eeneeeeneeeeeeeeees 420 
’, (single quote) read macro character [14.4.6] .........eceeeee eee eee eee e renee eee eeeee 424 
*, (back quote) read macro character [14.4.6] ........ceeceeeeee eee e eee e ee eeeeeneeeees 424 
, (vertical bar) read macro character [14.4.6] ........ eee eee cece ener eee e ener eee enenes 424 


@, Break Package command [20.2.9]..... 2.0 ccee eee c eee e eee e eee eee eee enenneenes 745 





